@getollie/cli

Ollie is a lightweight coding agent that runs against an OpenAI-compatible model endpoint. Its main agent uses a restricted Bash workspace powered by just-bash by default, with explicit native host workspace access available when required.

For the RL rollout use case and architecture, see the Ollie repository.

Install

Ollie requires Node.js 22 or later.

npm install --global @getollie/cli
ollie doctor

Quick start

Configure an OpenAI-compatible endpoint and run a task:

export OPENAI_API_KEY=...
# export OPENAI_BASE_URL=https://your-endpoint.example/v1

ollie 'summarize this repository'

Run shell source directly in the restricted runtime:

ollie exec pwd
ollie exec 'find . -type f | sort'

Prompts and complex shell source should be quoted so the host shell does not interpret them first.

Commands

ollie [agent options] [<prompt...> | -]
ollie agent [agent options] [<prompt...> | -]
ollie exec [exec options] <command...>
ollie doctor [doctor options]

The root command runs the model agent. ollie agent is the equivalent explicit form. ollie exec runs shell source without making a model call, and ollie doctor validates the local setup.

When no prompt argument is given, Ollie reads the prompt from piped or redirected stdin. A sole - reads stdin explicitly, including from an interactive terminal:

cat prompt.txt | ollie --model gpt-5.5
ollie --model gpt-5.5 - < prompt.txt

If prompt text is provided as an argument, it takes precedence and stdin is not read. An empty stdin prompt is rejected.

Configuration

Configuration precedence is CLI options, environment variables, then defaults.

Model runs require a nonempty OPENAI_API_KEY. Set OPENAI_BASE_URL for a custom OpenAI-compatible endpoint. OLLIE_PROVIDER_NAME defaults to openai; set it to google for Gemini-compatible endpoints that return thought signatures.

--reasoning-effort rides on every model request of a run, delegated executor runs included, as reasoning_effort in the request body. The level is forwarded as given, because each endpoint names its own levels (low, medium, and high for OpenAI models); leaving the option unset keeps the server's default.

--extra-request-header adds an extra HTTP header to every chat request of a run, delegated executor runs included. It is repeatable and written as Name: value:

ollie --extra-request-header 'X-Proxy-Tool-Calling: native' 'fix the failing test'

OLLIE_EXTRA_REQUEST_HEADERS sets the same headers from the environment as a JSON object:

export OLLIE_EXTRA_REQUEST_HEADERS='{"X-Proxy-Tool-Calling":"native"}'

Header names are compared case-insensitively, and --extra-request-header overrides an environment header of the same name. Values are trimmed and must be nonempty. Extra headers are added to the request Ollie already builds, so passing Authorization replaces the one derived from OPENAI_API_KEY.

Agent options

| Option | Environment | Description | | --- | --- | --- | | --cwd <path> | OLLIE_CWD | Primary host workspace; defaults to the current directory | | --workspace-path <path> | OLLIE_WORKSPACE_PATH | Logical primary mount target and sandbox working directory; defaults to /workspace | | -v, --volume <source:target> | OLLIE_VOLUMES | Add a read/write directory mount; repeatable | | --model <model> | OLLIE_MODEL | Model ID; defaults to gpt-5.5 | | --reasoning-effort <effort> | OLLIE_REASONING_EFFORT | reasoning_effort sent with every model request; unset leaves the server's default | | --extra-request-header <name:value> | OLLIE_EXTRA_REQUEST_HEADERS | Extra HTTP header sent with every model request; repeatable | | --mode <sandbox\|native> | OLLIE_WORKSPACE_MODE | Main-agent workspace backend; defaults to sandbox | | --executor <kind> | OLLIE_EXECUTOR | Optional remote delegation: none, daytona, or vercel; defaults to none | | --max-steps <number> | OLLIE_MAX_STEPS | Maximum model/tool steps; defaults to 20 | | --ndjson | — | Emit newline-delimited event records | | --no-color | — | Disable colored human-readable output |

Options must appear before prompt text. Once the prompt begins, option-looking arguments become part of it:

ollie --model gpt-5.5 --max-steps 30 'fix the failing test'
ollie 'explain this option' --model literal
# The second prompt is: explain this option --model literal

Use -- when a prompt begins with an option or the reserved names agent, exec, or doctor:

ollie -- exec --version
# prompt: exec --version

Exec options

| Option | Environment | Description | | --- | --- | --- | | --cwd <path> | OLLIE_CWD | Primary host workspace; defaults to the current directory | | --workspace-path <path> | OLLIE_WORKSPACE_PATH | Primary path inside the restricted runtime; defaults to /workspace | | -v, --volume <source:target> | OLLIE_VOLUMES | Add a read/write directory mount; repeatable | | --ndjson | — | Emit one captured command-result record |

Exec options must appear before command text. Later option-looking arguments belong to the command:

ollie exec printf --verbose
ollie exec -- --help

Doctor options

| Option | Description | | --- | --- | | --cwd <path> | Working directory to validate | | --model <model> | Model ID to validate | | --json | Emit one JSON diagnostic document |

Workspace mounts

In default sandbox mode, --workspace-path is the primary mount target, shell working directory, and sandbox-native Git root. In native mode, the primary host source is the actual working directory; mount targets remain logical navigation labels while tools use their host source paths. With defaults:

ollie --cwd ./project 'inspect this project'

mounts ./project at /workspace.

Additional mounts use Docker-style directory syntax:

ollie \
  --cwd ./project \
  --workspace-path /app \
  -v /tmp/artifacts:/logs/artifacts \
  -v ./reference:/reference:ro \
  'inspect the project and artifacts'

Sources may be relative host paths. Targets must be absolute POSIX paths. Mounts are read/write by default; append :ro for a read-only mount. Read-only mounts are supported only in sandbox workspace mode without a Daytona or Vercel executor. Duplicate, nested, missing, file-level, reserved, and unsupported mode-suffixed mounts are rejected. Among --cwd and volumes targeting workspacePath, the last argument wins.

OLLIE_VOLUMES is a JSON array:

export OLLIE_VOLUMES='["/tmp/artifacts:/logs/artifacts"]'

One agent run keeps one workspace backend, so filesystem changes survive across tool calls. Each shell call has fresh shell state; cd, aliases, functions, and exported variables do not carry into the next call. In native mode each call is a fresh /bin/sh -lc process at the primary host source.

Output formats

By default, agent runs produce human-readable output. With --ndjson, Ollie emits one event per line:

• text: assistant text;
• tool-call: a workspace or delegated tool invocation;
• tool-result: the corresponding result;
• error: an unsuccessful run;
• done: normal completion.

Delegated tool events include "source":"delegate".

ollie exec --ndjson emits one command-result record:

{"exitCode":0,"stdout":"hello\n","stderr":"","durationMs":3,"timedOut":false}

Automation should require both a successful process status and a final done event for agent runs.

Workspace modes and remote executors

• --mode sandbox (default) gives the main agent restricted in-process Just Bash tools. It may be combined with --executor daytona or --executor vercel to delegate bounded child-agent work to an isolated remote sandbox.
• --mode native gives the main agent direct host process and filesystem tools. Commands run with the current user's permissions and inherited environment and are not isolated. Host executables, package managers, network access, and absolute paths outside configured workspaces are available, so credentials and permanent host effects require care. Native mode does not support executors.

For Daytona, configure DAYTONA_API_KEY and optionally DAYTONA_API_URL, DAYTONA_TARGET, or OLLIE_DAYTONA_SNAPSHOT. For Vercel, configure VERCEL_OIDC_TOKEN, or VERCEL_TOKEN with VERCEL_TEAM_ID and VERCEL_PROJECT_ID; use OLLIE_VERCEL_RUNTIME or OLLIE_VERCEL_SNAPSHOT_ID to select the environment.

Remote delegated tasks can synchronize mounted workspaces before and after execution. Executor sessions persist across delegated tasks in one sandbox-mode agent run and are disposed when the run finishes. ollie exec always uses the restricted Just Bash runtime; it does not accept --mode or --executor.

Migrating from the local executor

--executor local and OLLIE_EXECUTOR=local have been removed. Use --mode native or OLLIE_WORKSPACE_MODE=native when the main agent should directly use local native tools. This removes the extra delegated model call and the delegateTask synchronization argument; Daytona and Vercel remain optional remote delegation providers.

Sandbox-native Git

The restricted runtime provides git through isomorphic-git. Supported commands are init, clone, status, add, commit, log, diff, branch, checkout, remote, config, fetch, pull, and push.

Remote operations accept HTTPS URLs only. SSH remotes, hooks, submodules, signing, editors, pagers, and advanced pathspecs or options are unsupported.

Diagnostics

ollie doctor
ollie doctor --json

Doctor validates local configuration without making a model call.

Transient provider failures

Chat completions are retried twice over, and both layers are silent:

• The AI SDK retries the request itself up to 6 times with exponential backoff whenever it can classify the failure as transient — 5xx, 408, 409, 429, and transport errors — honouring retry-after headers. This budget is per step, so a long run can retry more than 6 times in total.
• Ollie retries a request up to 6 more times when it opened successfully and then failed mid-stream, which the SDK cannot retry. Only the failed request is repeated: the steps already taken stay taken, and the retry applies only while that request has produced no output of its own, so nothing already shown to you is replayed and no tool runs twice. Errors are judged on structured fields only (isRetryable, status codes, transport codes, and provider error codes), read off the raw error record, which keeps the status the parsed one loses; anything unrecognised is treated as terminal and fails immediately.

A run can therefore pause for around two minutes before reporting a provider outage. Interrupting with Ctrl-C during a backoff stops it right away.

Exit status

• Root ollie and ollie agent return 1 for provider, transport, setup, or runtime failures, maximum-step exhaustion, or incomplete streams.
• Interrupted agents return 130 when the abort is reported through the run error path.
• ollie exec returns the restricted command's exit code, 124 on timeout, 130 for SIGINT, and 143 for SIGTERM.
• ollie doctor returns 1 when a required check fails.
• Invalid CLI usage and uncaught CLI errors return nonzero.

Safety

Mounted workspaces are read/write, host-backed, and persistent. The restricted runtime reduces the available command surface but is not a hardened OS isolation boundary. Native mode is explicitly unisolated and can access host paths, inherited credentials, executables, and network services with the current user's authority. Use an appropriate outer process, container, or VM policy for untrusted workloads.