---
title: internal/service
description: Go API reference for the service package.
---

<!-- Code generated by gomarkdoc. DO NOT EDIT -->

# service

```go
import "github.com/jbcom/radioactive-ralph/internal/service"
```

Package service manages per\-user OS service units for radioactive\-ralph.

Platform dispatch:

- macOS → launchd user agent \(\~/Library/LaunchAgents/jbcom.radioactive\-ralph.\<variant\>.plist\)
- Linux/WSL → systemd user unit \(\~/.config/systemd/user/radioactive\_ralph\-\<variant\>.service\)
- Homebrew → brew\-services wrapper \(invokes the launchd/systemd path\)

Gating:

- Variants with SafetyFloors.RefuseServiceContext = true refuse to install. Running savage/old\-man/world\-breaker under a service manager is operator malpractice \(they burn money or force\-push repos; neither should be on a cron\).
- Variants with a confirmation gate require the operator to have passed the gate flag to \`radioactive\_ralph service install\` explicitly.

Service\-context detection at \`radioactive\_ralph run\` time uses:

- LAUNCHED\_BY=launchd \(our own plist sets this\)
- INVOCATION\_ID set \(systemd user services set this\)
- RALPH\_SERVICE\_CONTEXT=1 \(manual override for tests\)

Supervisor refuses to spawn a RefuseServiceContext variant when any of those are set.

## Index

- [Variables](<#variables>)
- [func Install\(opts InstallOptions\) \(path string, err error\)](<#Install>)
- [func IsServiceContext\(\) bool](<#IsServiceContext>)
- [func Uninstall\(opts InstallOptions\) error](<#Uninstall>)
- [func UnitName\(b Backend, v variant.Name\) string](<#UnitName>)
- [func UnitPath\(b Backend, home string, v variant.Name\) string](<#UnitPath>)
- [type Backend](<#Backend>)
  - [func DetectBackend\(\) Backend](<#DetectBackend>)
- [type InstallOptions](<#InstallOptions>)


## Variables

<a name="ErrGateNotConfirmed"></a>ErrGateNotConfirmed is returned when a gated variant is installed without GateConfirmed=true.

```go
var ErrGateNotConfirmed = errors.New("service: gated variant requires explicit confirmation")
```

<a name="ErrMissingRalphBin"></a>ErrMissingRalphBin is returned when RalphBin is empty.

```go
var ErrMissingRalphBin = errors.New("service: RalphBin required")
```

<a name="ErrRefuseServiceContext"></a>ErrRefuseServiceContext is returned when the variant pins RefuseServiceContext=true.

```go
var ErrRefuseServiceContext = errors.New("service: variant refuses to run in a service context")
```

<a name="ErrUnsupportedBackend"></a>ErrUnsupportedBackend is returned for platforms we don't manage.

```go
var ErrUnsupportedBackend = errors.New("service: unsupported platform")
```

<a name="Install"></a>
## func [Install](<https://github.com/jbcom/radioactive-ralph/blob/main/internal/service/service.go#L135>)

```go
func Install(opts InstallOptions) (path string, err error)
```

Install writes the unit file for the given variant. Does not load it into launchd/systemd — callers do that via \`radioactive\_ralph service start\` to keep Install a pure filesystem operation \(trivial to test and to undo\).

<a name="IsServiceContext"></a>
## func [IsServiceContext](<https://github.com/jbcom/radioactive-ralph/blob/main/internal/service/service.go#L216>)

```go
func IsServiceContext() bool
```

IsServiceContext reports whether the current process looks like it's running under a service manager \(launchd / systemd \-\-user\). Checked in pre\-flight before spawning a RefuseServiceContext variant.

<a name="Uninstall"></a>
## func [Uninstall](<https://github.com/jbcom/radioactive-ralph/blob/main/internal/service/service.go#L190>)

```go
func Uninstall(opts InstallOptions) error
```

Uninstall removes the unit file. Returns nil if already absent.

<a name="UnitName"></a>
## func [UnitName](<https://github.com/jbcom/radioactive-ralph/blob/main/internal/service/service.go#L65>)

```go
func UnitName(b Backend, v variant.Name) string
```

UnitName returns the canonical service unit name for a variant. launchd: "jbcom.radioactive\-ralph.green" systemd: "radioactive\_ralph\-green"

<a name="UnitPath"></a>
## func [UnitPath](<https://github.com/jbcom/radioactive-ralph/blob/main/internal/service/service.go#L78>)

```go
func UnitPath(b Backend, home string, v variant.Name) string
```

UnitPath returns the on\-disk path where the unit file will be written. Callers pass the operator's home dir \(tests inject a tmpdir\).

<a name="Backend"></a>
## type [Backend](<https://github.com/jbcom/radioactive-ralph/blob/main/internal/service/service.go#L39>)

Backend identifies which platform mechanism is in use.

```go
type Backend string
```

<a name="BackendLaunchd"></a>

```go
const (
    // BackendLaunchd is macOS per-user launchd agent.
    BackendLaunchd Backend = "launchd"
    // BackendSystemdUser is Linux/WSL systemd user unit.
    BackendSystemdUser Backend = "systemd-user"
    // BackendUnsupported is returned for platforms we don't manage.
    BackendUnsupported Backend = "unsupported"
)
```

<a name="DetectBackend"></a>
### func [DetectBackend](<https://github.com/jbcom/radioactive-ralph/blob/main/internal/service/service.go#L51>)

```go
func DetectBackend() Backend
```

DetectBackend returns the appropriate backend for the current OS.

<a name="InstallOptions"></a>
## type [InstallOptions](<https://github.com/jbcom/radioactive-ralph/blob/main/internal/service/service.go#L92-L113>)

InstallOptions configures an install.

```go
type InstallOptions struct {
    // Backend overrides the detected platform. Empty = detect.
    Backend Backend
    // HomeDir overrides os.UserHomeDir. Empty = use os.UserHomeDir().
    HomeDir string
    // RalphBin is the absolute path to the radioactive_ralph binary that
    // the unit should exec. Required.
    RalphBin string
    // RepoPath is the operator's repo — written into the unit as the
    // working directory for the daemon.
    RepoPath string
    // Variant is the variant profile to install for. Required.
    Variant variant.Profile
    // GateConfirmed must be true when Variant has a ConfirmationGate.
    // Enforces "operator explicitly passed --confirm-X to
    // radioactive_ralph service install" so gates aren't bypassed via
    // the service wrapper.
    GateConfirmed bool
    // ExtraEnv is merged into the unit's environment block. Callers use
    // this for RALPH_SPEND_CAP_USD etc.
    ExtraEnv map[string]string
}
```

Generated by [gomarkdoc](<https://github.com/princjef/gomarkdoc>)