> This page is also available as Markdown: append .md to its URL. The full index of Sikaru docs is at https://docs.sikaru.ai/llms.txt. Code examples use only operations from the public API reference at https://docs.sikaru.ai/api-reference.

# Local compute

Commands and contracts on this page (native `sikaru` binary; no Python companion or provider registration):

1. Run: `sikaru exec --project PROJECT --agent AGENT --workspace /absolute/workspace --prompt "..."` (or `--prompt-file /absolute/task.txt`). Needs `SIKARU_API_KEY`. Final stdout is one JSON object; progress goes to stderr. `usage.available: false` means usage was not supplied, not zero cost.
2. Exit codes: 0 completed with confirmed cleanup; 1 failed; 2 approval required, parked after cleanup; 3 cancelled, including an explicit deadline; 4 recovery required or cleanup unconfirmed. Check `status`, `cleanup`, and `cancel_acknowledged` separately.
3. Continue: `sikaru exec --project PROJECT --workspace /absolute/workspace --resume /absolute/state [--prompt "..."]` using the exact returned `state_dir` and the original physical workspace.
4. Options: `--approval-wait 60` (keep executor available up to 60 s for approval), `--timeout 3600` (bound the invocation). Executor credentials cannot approve; controllers approve through generated run operations.
5. Controller commands: `compute-environments`, `compute-attachments`, `compute-workers`, `compute-credentials`, `compute-operations` (use `--help` and `--schema`). Session turns require the admitted `compute.execute` capability.
6. Containers: `sikaru compute serve --bootstrap -` (executor bootstrap on stdin); `sikaru compute worker --bootstrap <file> --launcher <path> --concurrency 4` (`--once` drains one queue page).
7. Executor bootstrap fields: `project_id`, `session_id`, `attachment_id`, `owner_epoch`, `workspace_generation`, `journal_id`, `credential_id`, `token`, `workspace_provenance`, `workspace`, `state_dir`. Worker bootstrap fields: `project_id`, `environment_id`, `token`, `state_dir`. Private input files mode 0600 owned by current user; state directories mode 0700, no symlink path components.
8. Launcher protocol: version 1 JSON over stdin for `launch`, `status`, `teardown`, with a stable `launch_id`.
9. Timing: startup bound 180 seconds; ready/heartbeat acknowledgments renew a 60-second lease.

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.

```mermaid
flowchart LR
    Hosted["Hosted agent orchestration"] -->|"Admitted operations"| Exec["sikaru executor on your machine"]
    Exec --> Workspace["Your workspace directory"]
    Exec -->|"Task inputs and outputs needed for reasoning"| Hosted
    Exec --> Out["One JSON result on stdout"]
```

Build or install the binary from the [CLI repository](https://github.com/aadi-labs/sikaru-cli) until coordinated packages are published. This workflow requires no Python companion or provider registration.

## Run a task

```sh
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.

| Exit | Outcome                                   |
| ---- | ----------------------------------------- |
| 0    | Completed with confirmed cleanup          |
| 1    | Failed                                    |
| 2    | Approval required, parked after cleanup   |
| 3    | Cancelled, including an explicit deadline |
| 4    | Recovery required or cleanup unconfirmed  |

> **Warning**
>
> 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

```sh
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.

| Option               | Effect                                                               |
| -------------------- | -------------------------------------------------------------------- |
| `--approval-wait 60` | Keep the executor available for up to 60 seconds of approval waiting |
| `--timeout 3600`     | Bound 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.

> **Warning**
>
> 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:

```sh
sikaru compute serve --bootstrap - < /absolute/private-executor.json
sikaru compute worker --bootstrap /absolute/private-worker.json \
  --launcher /absolute/customer-launcher --concurrency 4
```

| Bootstrap | Fields                                                                                                                                                                                                      |
| --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Executor  | `project_id`, `session_id`, `attachment_id`, `owner_epoch`, `workspace_generation`, `journal_id`, `credential_id`, `token`, `workspace_provenance`, `workspace`, and `state_dir`. The workspace must exist. |
| Worker    | `project_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.

> **Note**
>
> 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](/build/tools-and-connections)

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

#### [CLI](/sdks-and-cli/cli)

Install and use the native CLI.