runhost

package
v0.7.7-dev.1 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 2, 2026 License: MIT Imports: 27 Imported by: 0

Documentation

Overview

Package runhost holds what a remote runhost is made of on both sides of the SSH connection that reaches it: where things live on the server, the device's record of each runhost, the device's keys, the line that installs a run key behind its forced command, and the frames the server's service answers in.

A remote runhost is a Linux server the person owns, set up by the CLI or the desktop over SSH, that runs that person's runs. On the server a dedicated user, agentry, runs the `agentry runhost service` as a systemd user service. The service listens on an owner-only Unix socket and nothing else. A device reaches it with its own run key, which the server's authorized_keys holds with `restrict` and a forced `agentry runhost serve`: whatever command the device asks for, sshd runs serve, which relays the session to the socket carrying the asked verb. So SSH is the only way in, the run key opens no shell and forwards nothing, and the server opens no network port.

Index

Constants

View Source
const (
	// User is the server account that runs the service.
	User = "agentry"
	// Home is that account's home directory.
	Home = "/var/lib/agentry"
	// BinDir holds the links to the CLI and runsc in use.
	BinDir = Home + "/bin"
	// CLIPath is the CLI the service and serve run.
	CLIPath = BinDir + "/agentry"
	// ShellPath is the account's login shell: a link to the CLI, which under
	// this name runs the forced command and nothing else (LoginShell).
	ShellPath = BinDir + "/" + ShellName
	// ShellName is the login shell's file name.
	ShellName = "agentry-shell"
	// RunscPath is the runsc the Docker daemon's runtimes name.
	RunscPath = BinDir + "/runsc"
	// StateDir is the service's own state: the runhost's configuration and
	// the paired devices.
	StateDir = Home + "/runhost"
	// ConfigFile is the runhost's configuration (ServerConfig).
	ConfigFile = StateDir + "/config.json"
	// DevicesFile lists the paired devices (Device).
	DevicesFile = StateDir + "/devices.json"
	// SettingsDir holds the runhost's settings that only the admin sign-in
	// changes: root's, outside the agentry account's home, so neither the
	// service nor anything a run key reaches can write them.
	SettingsDir = "/etc/agentry-runhost"
	// UnsafeModeFile says "on" when runs on the runhost are compiled as
	// Unsafe Mode runs; absent, or anything else, is off.
	UnsafeModeFile = SettingsDir + "/unsafe-mode"
	// AuthorizedKeys is where the run keys are installed.
	AuthorizedKeys = Home + "/.ssh/authorized_keys"
	// UnitName is the systemd user unit of the service.
	UnitName = "agentry-runhost.service"
	// SocketName is the service's socket under the user's runtime directory.
	SocketName = "agentry-runhost.sock"
	// RunscRuntime and RunscUDSRuntime are the Docker daemon's two gVisor
	// registrations: every run container, and the gateway, which reaches a
	// host Unix socket and so needs --host-uds=open.
	RunscRuntime    = "runsc"
	RunscUDSRuntime = "runsc-uds"
)

The server's layout. Everything the service owns lives under the agentry user's home, so the service can replace its own CLI and runsc without root.

View Source
const (
	OwnerAccount = "account"
	OwnerDevices = "devices"
)

Owner kinds.

View Source
const (
	// FrameOut is a line of narration for the person.
	FrameOut = "out"
	// FrameResult carries the verb's answer, as JSON.
	FrameResult = "result"
	// FrameExit ends the answer, with an exit code and, when it is not 0,
	// the reason.
	FrameExit = "exit"
	// FrameRelease answers a job's document: Text is ReleaseNeeded when the
	// release's archive must follow it, ReleaseHeld when the store holds it.
	FrameRelease = "release"
	// FrameData carries bytes of a sealed output, in order.
	FrameData = "data"
	// FrameStarted says the job runs under the service: Text is its id. A
	// device that leaves after it finds the job again with attach.
	FrameStarted = "started"
	// FrameEvent carries one event of a session, as the session protocol
	// wrote it, in Result.
	FrameEvent = "event"
	// FrameOpen asks the device to open an address in the person's browser
	// during a sign-in: Text is the address, Result an Open.
	FrameOpen = "open"
)

Frame types.

View Source
const (
	ReleaseNeeded = "needed"
	ReleaseHeld   = "held"
)

The two answers of a release frame.

View Source
const DataChunk = 256 << 10

DataChunk is the most bytes one data frame carries.

View Source
const DeviceIDFile = "runhost-device-id"

DeviceIDFile holds this device's id, under the runner home.

View Source
const MaxLine = 4 << 20

MaxLine bounds one line of the wire format.

View Source
const RecordsFile = "runhosts.yaml"

RecordsFile is the device's record of its runhosts, under the runner home.

View Source
const ServeCommand = CLIPath + " runhost serve"

ServeCommand is the forced command of every run key.

Variables

View Source
var ErrHostKeyChanged = errors.New("the runhost's host key is not the one pinned at setup")

ErrHostKeyChanged means the server offered a host key other than the one pinned at setup: someone may be in the way, or the server was reinstalled.

View Source
var ErrNoExit = errors.New("the runhost's answer ended before it finished")

ErrNoExit means the answer ended without its exit frame: the connection dropped, or the service stopped mid-answer.

Functions

func AuthorizedKeyLine

func AuthorizedKeyLine(publicKey, deviceID string) string

AuthorizedKeyLine is the authorized_keys line that installs a run key: the key may run nothing but serve, and restrict takes away the pty, port, agent and X11 forwarding and the user's rc file.

func DeleteKeys

func DeleteKeys(name string) error

DeleteKeys removes the runhost name's keys from the system keychain; keys already gone are not an error.

func DeviceComment

func DeviceComment(deviceID string) string

DeviceComment is the comment a device's run key carries.

func DeviceID

func DeviceID(home string) (string, error)

DeviceID is this device's id, made the first time it is asked for.

func IsVerb

func IsVerb(v string) bool

IsVerb says whether v is a verb a run key may ask for. sshd hands serve the asked command in SSH_ORIGINAL_COMMAND, and serve relays only these to the service, which answers the ones it knows and refuses the rest.

func LoginShell

func LoginShell(args []string) (handled, serve bool, refusal string)

LoginShell decides what the CLI does when it runs as the agentry account's login shell, ShellPath, which sshd and su know it by. sshd runs a session's command as `shell -c command`, and the forced command makes that `-c` + ServeCommand whatever the device asked. Under that name everything else is refused: a login, an interactive shell, and any other -c command, so the account has no shell even if a key were installed without its forced command. handled is false when the CLI runs under any other name; serve is true when the command is serve.

func SaveKeys

func SaveKeys(name string, k *DeviceKeys) error

SaveKeys keeps k in the system keychain for the runhost name.

func Serve

func Serve(ctx context.Context, original string, stdin io.Reader, stdout io.Writer, socket string) int

Serve is the forced command of every run key. sshd runs it whatever the device asked for, with the asked command in SSH_ORIGINAL_COMMAND; Serve relays the session to the service's socket only when that command is a run key's verb (IsVerb), and otherwise answers with a refusal and exit status 2. It never runs anything itself. It returns the exit status the session ends with: the service's exit frame's.

func ServeSocket

func ServeSocket() string

ServeSocket is the service's socket as serve finds it: under XDG_RUNTIME_DIR, which the SSH session's login sets, or else under /run/user for this uid.

func SocketPath

func SocketPath(uid int) string

SocketPath is the service's socket for the agentry user's uid.

func UnsafeModeOn added in v0.7.7

func UnsafeModeOn(file string) bool

UnsafeModeOn says whether the runhost's Unsafe Mode setting, read from file (UnsafeModeFile on the server), is on.

func ValidName

func ValidName(name string) error

ValidName says whether name can name a runhost: lower-case letters, digits and inner hyphens, at most 32 characters. It becomes part of keychain accounts and of the run setup's labels.

func WriteRequest

func WriteRequest(w io.Writer, r Request) error

WriteRequest writes a request line.

Types

type Answer

type Answer struct {
	Out    []string
	Result json.RawMessage
	Code   int
	Error  string
}

Answer is a whole answer, read.

func ReadAnswer

func ReadAnswer(r io.Reader, out func(string)) (Answer, error)

ReadAnswer reads frames until the exit frame, handing each narration line to out (which may be nil).

func ReadFrames added in v0.6.1017

func ReadFrames(r io.Reader, each func(Frame) error) (Answer, error)

ReadFrames reads frames until the exit frame, handing every frame to each (an error from each stops the read and is returned).

type Client

type Client struct {
	// contains filtered or unexported fields
}

Client is a device's connection to a runhost over its run key.

func DialRunhost

func DialRunhost(ctx context.Context, rec Record, keys *DeviceKeys) (*Client, error)

DialRunhost reaches the runhost rec over its run key. The server must offer exactly the host key pinned in rec; any other is refused.

func (*Client) Ask

func (c *Client) Ask(ctx context.Context, verb string, args []string, out func(string)) (Answer, error)

Ask asks the service verb with args and reads its whole answer. out, when not nil, receives the narration as it comes.

func (*Client) Call added in v0.6.1017

func (c *Client) Call(ctx context.Context, verb string, args []string, send func(io.Writer) error, each func(Frame) error) (Answer, error)

Call asks the service verb with args, gives send the session's input (closed when send returns; nil sends nothing), and hands every frame of the answer to each until the exit frame. An error from send or each ends the session.

func (*Client) CheckRestrictions

func (c *Client) CheckRestrictions(ctx context.Context) []Restriction

CheckRestrictions tries, over the run key, what the key must never do: run a command of its own, open a shell, take a terminal, and open a TCP channel through the server. Each must be refused.

func (*Client) Close

func (c *Client) Close() error

Close ends the connection.

type CreditsRecord added in v0.7.3

type CreditsRecord struct {
	Registry  string `yaml:"registry" json:"registry"`
	TokenID   string `yaml:"tokenID" json:"tokenID"`
	TokenName string `yaml:"tokenName" json:"tokenName"`
	AddedAt   string `yaml:"addedAt" json:"addedAt"`
}

CreditsRecord names a runhost's credits token, which the runhost alone holds: its registry, its id and its name among the account's tokens.

type Device

type Device struct {
	// ID is the device's own id, the run key's comment.
	ID string `json:"id"`
	// Label is the device's host name, for a person to tell devices apart.
	Label string `json:"label"`
	// RunKey is the run key's public half, in authorized_keys form.
	RunKey string `json:"runKey"`
	// SealKey is the sealing key's public half, base64.
	SealKey string `json:"sealKey"`
	// PairedAt is when the device was paired, RFC 3339.
	PairedAt string `json:"pairedAt"`
}

Device is one paired device, as the server keeps it.

type DeviceKeys

type DeviceKeys struct {
	Run  ed25519.PrivateKey
	Seal *ecdh.PrivateKey
}

DeviceKeys are a device's two keys for one runhost: the ed25519 run key it signs in with, and the X25519 sealing key the runhost seals its output to.

func LoadKeys

func LoadKeys(name string) (*DeviceKeys, error)

LoadKeys reads the runhost name's keys from the system keychain.

func NewDeviceKeys

func NewDeviceKeys() (*DeviceKeys, error)

NewDeviceKeys makes a fresh pair.

func (*DeviceKeys) RunPublic

func (k *DeviceKeys) RunPublic() (string, error)

RunPublic is the run key's public half, in authorized_keys form without a comment.

func (*DeviceKeys) SealPublic

func (k *DeviceKeys) SealPublic() string

SealPublic is the sealing key's public half, base64.

func (*DeviceKeys) Signer

func (k *DeviceKeys) Signer() (ssh.Signer, error)

Signer is the run key as an SSH signer.

type Devices

type Devices struct {
	Devices []Device `json:"devices"`
}

Devices is the devices file.

type Frame

type Frame struct {
	Type   string          `json:"type"`
	Text   string          `json:"text,omitempty"`
	Result json.RawMessage `json:"result,omitempty"`
	Code   int             `json:"code,omitempty"`
	Error  string          `json:"error,omitempty"`
	Data   []byte          `json:"data,omitempty"`
}

Frame is one line of the service's answer.

type FrameWriter

type FrameWriter struct {
	// contains filtered or unexported fields
}

FrameWriter writes frames; it is safe for concurrent use.

func NewFrameWriter

func NewFrameWriter(w io.Writer) *FrameWriter

NewFrameWriter writes frames to w.

func (*FrameWriter) Data added in v0.6.1017

func (f *FrameWriter) Data(r io.Reader) error

Data writes r to its end as data frames.

func (*FrameWriter) Exit

func (f *FrameWriter) Exit(code int, err error) error

Exit ends the answer.

func (*FrameWriter) Frame added in v0.7.2

func (f *FrameWriter) Frame(fr Frame) error

Frame writes f as it is.

func (*FrameWriter) Out

func (f *FrameWriter) Out(format string, args ...any) error

Out writes a line of narration.

func (*FrameWriter) Release added in v0.6.1017

func (f *FrameWriter) Release(answer string) error

Release says whether a job's release must follow its document.

func (*FrameWriter) Result

func (f *FrameWriter) Result(v any) error

Result writes the verb's answer.

func (*FrameWriter) Started added in v0.7.2

func (f *FrameWriter) Started(id string) error

Started says job id runs under the service.

type Handler

type Handler func(ctx context.Context, req Request, in io.Reader, fw *FrameWriter) (int, error)

Handler answers one verb. in is the rest of the device's input after the request line (a job's document and release, for job). It writes its narration and result to fw and returns the exit code and, when it is not 0, why.

type Open added in v0.7.6

type Open struct {
	Relay string `json:"relay,omitempty"`
	Port  int    `json:"port,omitempty"`
	Code  string `json:"code,omitempty"`
}

Open is what a sign-in's open frame asks of the device besides the address: to relay the browser's answer back to the runhost (Relay names the sign-in, Port is the callback's port on the device's loopback), or to show the person a code to enter on the page.

type Owner

type Owner struct {
	// Kind is "account" or "devices".
	Kind string `json:"kind" yaml:"kind"`
	// Registry and Handle name the account, for Kind "account".
	Registry string `json:"registry,omitempty" yaml:"registry,omitempty"`
	Handle   string `json:"handle,omitempty" yaml:"handle,omitempty"`
}

Owner is who a runhost belongs to: the Agentry account the setting-up device was signed in to, or, set up signed out, the paired devices alone.

func (Owner) String

func (o Owner) String() string

String says the owner as a person reads it.

type Record

type Record struct {
	Name string `yaml:"name" json:"name"`
	// Host and Port are the server's SSH address, as the person gave it.
	Host string `yaml:"host" json:"host"`
	Port int    `yaml:"port" json:"port"`
	// HostKey is the server's host key, pinned at setup, in authorized_keys
	// form. Every later connection must be offered exactly this key.
	HostKey string `yaml:"hostKey" json:"hostKey"`
	// HostKeyFingerprint is HostKey's SHA256 fingerprint, for a person.
	HostKeyFingerprint string `yaml:"hostKeyFingerprint" json:"hostKeyFingerprint"`
	Owner              Owner  `yaml:"owner" json:"owner"`
	// DeviceID is the id this device paired under.
	DeviceID string `yaml:"deviceID" json:"deviceID"`
	// CLIVersion, Arch and OS are the server's, as of the last check.
	CLIVersion string `yaml:"cliVersion" json:"cliVersion"`
	Arch       string `yaml:"arch" json:"arch"`
	OS         string `yaml:"os" json:"os"`
	GVisor     string `yaml:"gvisor" json:"gvisor"`
	AddedAt    string `yaml:"addedAt" json:"addedAt"`
	// Capabilities are the runs the runhost takes, as its status said at
	// the last check.
	Capabilities map[string]bool `yaml:"capabilities,omitempty" json:"capabilities,omitempty"`
	// Credits is the Agentry credits token this device made for the
	// runhost and the runhost keeps, when there is one: never the token.
	Credits *CreditsRecord `yaml:"credits,omitempty" json:"credits,omitempty"`
	// SignIns are the model sign-ins this device made on the runhost, which
	// the runhost alone keeps: never a token.
	SignIns []SignInRecord `yaml:"signIns,omitempty" json:"signIns,omitempty"`
}

Record is what a device knows of one runhost.

type Records

type Records struct {
	Runhosts []Record `yaml:"runhosts"`
}

Records is the records file.

func LoadRecords

func LoadRecords(home string) (*Records, error)

LoadRecords reads the records file under home; a missing file is no runhosts.

func (*Records) Drop

func (r *Records) Drop(name string)

Drop removes the record named name.

func (*Records) Find

func (r *Records) Find(name string) (*Record, bool)

Find is the runhost named name.

func (*Records) Put

func (r *Records) Put(rec Record)

Put adds rec, or replaces the record of the same name.

func (*Records) Save

func (r *Records) Save(home string) error

Save writes the records file, owner-only, replacing it whole.

type Request

type Request struct {
	Verb string   `json:"verb"`
	Args []string `json:"args,omitempty"`
}

Request is what a device asks of the service.

func ReadRequest

func ReadRequest(r *bufio.Reader) (Request, error)

ReadRequest reads a request line.

type Restriction

type Restriction struct {
	What    string `json:"what"`
	Refused bool   `json:"refused"`
	Detail  string `json:"detail"`
}

Restriction is one thing a run key must not be able to do, and whether the server refused it.

type ServerConfig

type ServerConfig struct {
	// Name is the name the setting-up device gave the runhost.
	Name string `json:"name"`
	// Owner is who the runhost belongs to.
	Owner Owner `json:"owner"`
	// UnsafeMode is no longer read: the setting is UnsafeModeFile, which
	// only the admin sign-in writes. Kept so an older configuration reads.
	UnsafeMode bool `json:"unsafeMode,omitempty"`
	// InstalledDocker is whether setup installed Docker Engine, so that
	// remove may offer to take it away again.
	InstalledDocker bool `json:"installedDocker"`
	// GVisor is the gVisor release installed.
	GVisor string `json:"gvisor"`
	// SetUpAt is when setup finished, RFC 3339.
	SetUpAt string `json:"setUpAt"`
}

ServerConfig is the runhost's configuration, kept by the service.

type Service

type Service struct {
	Socket   string
	Handlers map[string]Handler
	// Log, when set, is told of each request and of failures to answer.
	Log func(format string, args ...any)
	// contains filtered or unexported fields
}

Service is the runhost's service: an owner-only Unix socket and the handlers of the verbs it answers.

func (*Service) Listen

func (s *Service) Listen() (net.Listener, error)

Listen opens the socket, owner-only: a stale socket from an earlier run is removed first, and the socket is created under a umask that gives no one else any bit, so there is no moment when another user could connect.

func (*Service) Serve

func (s *Service) Serve(ctx context.Context, l net.Listener) error

Serve answers connections on l until ctx is done, then waits for the answers in flight.

type SignInRecord added in v0.7.6

type SignInRecord struct {
	Vendor  string `yaml:"vendor" json:"vendor"`
	Label   string `yaml:"label,omitempty" json:"label,omitempty"`
	AddedAt string `yaml:"addedAt" json:"addedAt"`
}

SignInRecord names a model sign-in a runhost keeps: the vendor and the account the vendor named.

Directories

Path Synopsis
Package clirelease decides whether a CLI binary is one of Agentry's signed releases: SHA256SUMS signed with an update-signing key this build carries, a signed trusted comment naming the product and the version, and the binary's own line in those sums.
Package clirelease decides whether a CLI binary is one of Agentry's signed releases: SHA256SUMS signed with an update-signing key this build carries, a signed trusted comment naming the product and the version, and the binary's own line in those sums.
Package job is the document a device sends a remote runhost to start one run: the release it verified, what it decided about the run, and what the run needs from the device.
Package job is the document a device sends a remote runhost to start one run: the release it verified, what it decided about the run, and what the run needs from the device.
Package output is a remote run's output at rest on the runhost: the run's output folder packed into one tar of the members a device takes back, and that tar sealed to every paired device's sealing key, so the server keeps no plaintext output once the run has ended.
Package output is a remote run's output at rest on the runhost: the run's output folder packed into one tar of the members a device takes back, and that tar sealed to every paired device's sealing key, so the server keeps no plaintext output once the run has ended.
Package payload carries the files a run on a remote runhost takes from the device: its inputs, the files that answer its intake questions, the knowledge packs it attaches, its Writing Voice and its report design.
Package payload carries the files a run on a remote runhost takes from the device: its inputs, the files that answer its intake questions, the knowledge packs it attaches, its Writing Voice and its report design.
Package setup makes a Linux server the person owns into a remote runhost, over SSH, and takes it away again.
Package setup makes a Linux server the person owns into a remote runhost, over SSH, and takes it away again.
Package signin is a model sign-in made for a remote runhost: Claude Code's own sign-in, Sign in with ChatGPT and Sign in with GitHub for a Copilot plan, run on the runhost while the person's browser is on the device.
Package signin is a model sign-in made for a remote runhost: Claude Code's own sign-in, Sign in with ChatGPT and Sign in with GitHub for a Copilot plan, run on the runhost while the person's browser is on the device.
Package store is the runhost's store of the releases it has run: each one's archive and the facts it arrived with, encrypted at rest, so a later run of the same release need not send it again.
Package store is the runhost's store of the releases it has run: each one's archive and the facts it arrived with, encrypted at rest, so a later run of the same release need not send it again.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL