Skip to navigation
Run agents

Local compute

Run a hosted Sikaru agent against a directory on your own macOS or Linux machine or container with the native sikaru binary, then continue, approve, and clean up its work.
View as Markdown

Run a hosted Sikaru agent against a directory on your own macOS or Linux machine with the native sikaru binary. Orchestration stays hosted; admitted operations run on your machine.

Admitted operations Task inputs and outputs neededfor reasoning Hosted agent orchestration sikaru executor on your machine Your workspace directory One JSON result on stdout

Build or install the binary from the CLI repository until coordinated packages are published. This workflow requires no Python companion or provider registration.

Run a task

export SIKARU_API_KEY=YOUR_PROJECT_API_KEY
sikaru exec --project PROJECT --agent AGENT --workspace /absolute/workspace \
  --prompt "Inspect the project and write a short report"
  • --prompt-file /absolute/task.txt reads a prompt from a file.
  • A fresh invocation creates a fresh execution session, attachment and local state identity.
  • Caller files stay in place.
  • The final stdout is one JSON object; progress uses stderr.
  • usage.available: false means cost/usage was not supplied, not zero cost.
ExitOutcome
0Completed with confirmed cleanup
1Failed
2Approval required, parked after cleanup
3Cancelled, including an explicit deadline
4Recovery required or cleanup unconfirmed

Inspect status, cleanup and cancel_acknowledged separately. A completed run can still require cleanup. SIGINT/SIGTERM request cancellation and await owned process cleanup; a machine crash or SIGKILL cannot provide that proof.

Continue and approve

sikaru exec --project PROJECT --workspace /absolute/workspace --resume /absolute/state
sikaru exec --project PROJECT --workspace /absolute/workspace --resume /absolute/state \
  --prompt "Now summarize the changes"

Use the exact state_dir returned by the original command and the original physical workspace.

Default headless behavior parks on approval. Controllers approve through ordinary generated run operations; executor credentials cannot approve.

OptionEffect
--approval-wait 60Keep the executor available for up to 60 seconds of approval waiting
--timeout 3600Bound the invocation

Approval waiting does not suspend lease renewal or cancellation.

Reconnect and restart

Transport reconnect keeps the process identity and immutable receipts. Process restart requires confirmed teardown and a new claim/epoch/credential; --resume performs this only when original workspace and journal evidence permit it.

Unknown effects are never rerun automatically. Preserve evidence, explicitly abandon uncertain attachments through the controller API, and use fresh workspace provenance only after teardown is confirmed.

Customer containers and workers

A controller can create an execution session and environment, bind an attachment, claim it and issue an attachment credential through the generated compute-environments, compute-attachments, compute-workers, compute-credentials and compute-operations commands. Use each command’s --help and --schema for the generated request fields. Session turns still require the admitted compute.execute capability; environment selection grants no additional authority.

Provision your container independently, install the same binary inside it, and pass only its restricted bootstrap through stdin:

sikaru compute serve --bootstrap - < /absolute/private-executor.json
sikaru compute worker --bootstrap /absolute/private-worker.json \
  --launcher /absolute/customer-launcher --concurrency 4
BootstrapFields
Executorproject_id, session_id, attachment_id, owner_epoch, workspace_generation, journal_id, credential_id, token, workspace_provenance, workspace, and state_dir. The workspace must exist.
Workerproject_id, environment_id, token, and state_dir

Private input files must be owned by the current user and mode 0600. State directories are mode 0700 and cannot contain symlink path components.

Never put credentials in command arguments. Worker credentials cover one queue; executor credentials cover one attachment and cannot read project-wide runs.

Launcher protocol

The customer launcher implements version 1 JSON over stdin for launch, status and teardown, with a stable launch_id.

  • Only launch receives the restricted executor credential.
  • Replies include the same version/launch ID, a status, and an immutable container/sandbox handle with creation proof.
  • A lost launch response requires status reconciliation, never another launch.
  • Teardown must prove the same handle terminated; unknown cleanup produces recovery-required.
  • --once drains one queue page and reconciles owned launches before exiting.

Files, authority and readiness

The hosted harness, private instructions and model credentials stay with Sikaru. Task inputs and outputs needed for reasoning reach Sikaru; customer files stay on the execution host unless explicitly exported.

The directory is a working directory, not an isolation boundary. Local execution trusts the account and host; use your own container/account boundary when isolation is required. Task environments omit inherited SIKARU_* variables.

Task IO starts after readiness, workspace verification and authority checks.

  • The startup bound is 180 seconds.
  • Ready/heartbeat acknowledgments renew a 60-second lease with a conservative local deadline. Polling and credential renewal never extend that lease.
  • Empty work is not completion.
  • Idle polling honors bounded server hints; signal, lease and overall deadlines remain independently active.
  • Disconnected executors stop before their local lease expires.
  • Journals preserve intent and immutable receipts, never credentials or permission to replay unknown shell effects.
  • Hosted snapshots do not restore customer files.

Next steps

Tools and connections

Compare local compute with managed connections and product-owned tools.

CLI

Install and use the native CLI.