remote

Documentation

Overview

Package remote provides a RemoteRunner that implements sandbox.SandboxRunner by dialing a remote sandbox agent over gRPC (mTLS + bearer token auth).

The remote agent binary and config wiring land in PR8. This package ships the client only (ADR 0019).

Secret-ref invariant (ADR 0017): env values may carry unresolved secret:// references. RemoteRunner passes them verbatim to the agent — it MUST NOT attempt to resolve them. The agent resolves secret:// refs server-side.

Index

• type RemoteRunner
  • func NewRemoteRunner(cfg RemoteRunnerConfig) (*RemoteRunner, error)
  • func (r *RemoteRunner) Close() error
  • func (r *RemoteRunner) Exec(ctx context.Context, cmd []string) (*sandbox.ExecResult, error)
• type RemoteRunnerConfig

Types

type RemoteRunner

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

RemoteRunner implements sandbox.SandboxRunner by streaming commands to a remote sandbox agent over gRPC.

func NewRemoteRunner

func NewRemoteRunner(cfg RemoteRunnerConfig) (*RemoteRunner, error)

NewRemoteRunner dials the remote sandbox agent and returns a RemoteRunner. The connection is lazy-cached; subsequent Exec calls reuse it.

If a bearer Token is supplied without TLS, NewRemoteRunner returns an error unless AllowInsecure is set — sending a token over a cleartext connection would leak the credential (gRPC does not reject it because the runner's PerRPCCredentials.RequireTransportSecurity is intentionally false to allow the explicit local-dev/test opt-in).

func (*RemoteRunner) Close

func (r *RemoteRunner) Close() error

Close releases the underlying gRPC connection held by the runner.

func (*RemoteRunner) Exec

func (r *RemoteRunner) Exec(ctx context.Context, cmd []string) (*sandbox.ExecResult, error)

Exec runs cmd inside the remote sandbox and returns the combined result. env VALUES that contain secret:// references are passed verbatim to the agent — RemoteRunner does NOT resolve them (ADR 0017).

type RemoteRunnerConfig

type RemoteRunnerConfig struct {
	// Address is the gRPC target of the remote sandbox agent (host:port).
	Address string

	// Token is the bearer token sent in the "authorization" metadata header on
	// every RPC. Empty string means no bearer token is sent.
	Token string

	// TLS is the TLS configuration for mTLS dial. nil means insecure (useful
	// for unit tests; production always supplies a tls.Config with client certs).
	TLS *tls.Config

	// AllowInsecure permits a non-empty Token to be sent over an insecure
	// (non-TLS) connection. This is an explicit opt-in for tests and local
	// development ONLY. Without it, NewRemoteRunner rejects Token != "" &&
	// TLS == nil to prevent leaking the bearer token in cleartext.
	AllowInsecure bool

	// Profile is the requested sandbox security profile (e.g. "default",
	// "strict"). The agent clamps the effective profile to its configured
	// maximum-allowed value (PR8).
	Profile string

	// Image is the OCI image reference to use for command execution.
	Image string

	// Env is the base process environment sent to the agent. Values may be
	// unresolved secret:// references — the agent resolves them (ADR 0017).
	// RemoteRunner passes them verbatim; it MUST NOT resolve them.
	Env map[string]string

	// WorkDir is the working directory inside the container. Empty = image default.
	WorkDir string
}

RemoteRunnerConfig carries the dial-time and per-exec identity of a remote sandbox agent. Profile, Image, Env, and WorkDir are sent on every SandboxExecRequest; command-specific overrides are applied by Exec.