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
- Variables
- func AuthorizedKeyLine(publicKey, deviceID string) string
- func DeleteKeys(name string) error
- func DeviceComment(deviceID string) string
- func DeviceID(home string) (string, error)
- func IsVerb(v string) bool
- func LoginShell(args []string) (handled, serve bool, refusal string)
- func SaveKeys(name string, k *DeviceKeys) error
- func SealedEnvelopeJob(id string) string
- func Serve(ctx context.Context, original string, stdin io.Reader, stdout io.Writer, ...) int
- func ServeSocket() string
- func SocketPath(uid int) string
- func UnsafeModeOn(file string) bool
- func ValidName(name string) error
- func WriteRequest(w io.Writer, r Request) error
- type Answer
- type Client
- func (c *Client) Ask(ctx context.Context, verb string, args []string, out func(string)) (Answer, error)
- func (c *Client) Call(ctx context.Context, verb string, args []string, send func(io.Writer) error, ...) (Answer, error)
- func (c *Client) CheckRestrictions(ctx context.Context) []Restriction
- func (c *Client) Close() error
- type CreditsRecord
- type Device
- type DeviceKeys
- type Devices
- type Frame
- type FrameWriter
- func (f *FrameWriter) Data(r io.Reader) error
- func (f *FrameWriter) Exit(code int, err error) error
- func (f *FrameWriter) Frame(fr Frame) error
- func (f *FrameWriter) Out(format string, args ...any) error
- func (f *FrameWriter) Release(answer string) error
- func (f *FrameWriter) Result(v any) error
- func (f *FrameWriter) Started(id string) error
- type Handler
- type JobResult
- type Open
- type Owner
- type Record
- type Records
- type Request
- type Restriction
- type ServerConfig
- type Service
- type SessionFile
- type SessionInput
- type SignInRecord
Constants ¶
const ( // MaxSessionFile bounds one file a device adds to a session. MaxSessionFile = 512 << 20 // MaxEnvelope bounds a run's envelope, the runhost CLI's stdout. MaxEnvelope = 16 << 20 // OutputKeep is how long a finished job's sealed output waits for // collection. OutputKeep = 7 * 24 * time.Hour )
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.
const ( OwnerAccount = "account" OwnerDevices = "devices" )
Owner kinds.
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.
const ( ReleaseNeeded = "needed" ReleaseHeld = "held" )
The two answers of a release frame.
const DataChunk = 256 << 10
DataChunk is the most bytes one data frame carries.
const DeviceIDFile = "runhost-device-id"
DeviceIDFile holds this device's id, under the runner home.
const MaxLine = 4 << 20
MaxLine bounds one line of the wire format.
const RecordsFile = "runhosts.yaml"
RecordsFile is the device's record of its runhosts, under the runner home.
const ServeCommand = CLIPath + " runhost serve"
ServeCommand is the forced command of every run key.
Variables ¶
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.
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 ¶
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 ¶
DeleteKeys removes the runhost name's keys from the system keychain; keys already gone are not an error.
func DeviceComment ¶
DeviceComment is the comment a device's run key carries.
func IsVerb ¶
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 ¶
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 SealedEnvelopeJob ¶ added in v0.7.8
SealedEnvelopeJob is the job string a job's envelope is sealed under, so it never opens as the job's output.
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 ¶
SocketPath is the service's socket for the agentry user's uid.
func UnsafeModeOn ¶ added in v0.7.7
UnsafeModeOn says whether the runhost's Unsafe Mode setting, read from file (UnsafeModeFile on the server), is on.
Types ¶
type Answer ¶
type Answer struct {
Out []string
Result json.RawMessage
Code int
Error string
}
Answer is a whole answer, read.
func ReadAnswer ¶
ReadAnswer reads frames until the exit frame, handing each narration line to out (which may be nil).
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 ¶
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.
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 (*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.
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 ¶
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 JobResult ¶ added in v0.7.8
type JobResult struct {
Job string `json:"job"`
ExitCode int `json:"exitCode"`
// Done says the job has ended: its sealed output and envelope wait for
// collect. Next is the index after the last frame the answer carried.
Done bool `json:"done"`
Next int `json:"next,omitempty"`
}
JobResult is the job and attach verbs' answer.
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.
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 ¶
LoadRecords reads the records file under home; a missing file is no runhosts.
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.
type SessionFile ¶ added in v0.7.8
type SessionFile struct {
Name string `json:"name"`
Data []byte `json:"data"`
More bool `json:"more,omitempty"`
}
SessionFile is a chunk of a file a device adds to a session: More says another chunk of the same file follows.
type SessionInput ¶ added in v0.7.8
type SessionInput struct {
Command *json.RawMessage `json:"command,omitempty"`
File *SessionFile `json:"file,omitempty"`
}
SessionInput is one line of a session's input after the job: a command for the session protocol, or a chunk of a file the device adds.
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.
Source Files
¶
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. |