Skip to content

getting-started.md

Latest commit

 

History

History
167 lines (118 loc) · 3.66 KB

getting-started.md

File metadata and controls

167 lines (118 loc) · 3.66 KB

Getting Started

This guide is the longer version of the top-level README quick start.

Prerequisites

You need:

  • Apple Silicon
  • Ollama installed
  • Apple's container CLI installed

Recommended memory:

  • for local-model workflows, plan for at least 32 GB RAM
  • online-only workflows may work with less memory, but that is not yet verified in the current docs/test matrix

Install sources:

Initial setup

Open a Terminal in the repository root.

Make agentctl available on your PATH.

Recommended on macOS:

sudo ln -sf "$PWD/agentctl" /usr/local/bin/agentctl

User-local alternative:

mkdir -p "$HOME/bin"
ln -sf "$PWD/agentctl" "$HOME/bin/agentctl"
export PATH="$HOME/bin:$PATH"

Then run:

ollama pull gpt-oss:20b
ollama pull gemma4:26b-a4b-it-q4_K_M
# Matches the built-in Codex `qwen` profile
ollama pull qwen3.5:35b-a3b-coding-nvfp4
# Smaller model for direct `agentctl run --model ...` testing
ollama pull qwen3.5:9b-nvfp4
container system start

If local runtime launches cannot reach Ollama, follow networking.md.

Workspace model

agentctl run does not make the agent operate on the whole host machine by default. Instead, it mounts a chosen host directory into the container at /workdir.

In the default case:

  • the current directory becomes /workdir
  • the agent can read and write within that mounted directory tree
  • the agent does not get unrestricted access to the rest of your host filesystem through agentctl
  • this is why you normally start agentctl from the project or document folder you want the agent to work on

If you want to target a different directory, use:

agentctl run --workdir /path/to/project

First build

Build the curated images:

agentctl build

To preinstall multiple runtimes and choose a default:

agentctl build --runtimes codex,claude --default-runtime claude

First run

Start the default container for the current directory. That directory is mounted into the container as /workdir:

agentctl run

Common alternatives:

# Run Codex with a specific local profile
agentctl run -c profile=gemma

# Test a specific model directly
agentctl run --model qwen3.5:9b-nvfp4

# Pass a runtime-specific Claude launch flag
agentctl run --runtime claude -c dangerously-skip-permissions=true

# Use the runtime's online/provider-backed mode after logging in once
agentctl auth --runtime codex
agentctl run --runtime codex --online

# Start a shell instead of the runtime
agentctl run --shell

# Create a new container and auto-install Claude on first launch
agentctl run --runtime claude

# Install Codex explicitly in an existing container
agentctl run --runtime codex --install-runtime

# Start with a different curated image
agentctl run --image agent-python

# Keep the mounted workdir read-only
agentctl run --read-only

# Use a temporary container
agentctl run --temp

Useful follow-ups:

agentctl runtime list
agentctl feature list
agentctl refresh

Existing containers

When agentctl, runtime manifests, or runtime adapters change, update existing containers in place with:

agentctl refresh

This is the normal non-destructive update path.

To restore image-owned defaults such as config.toml, local_models.json, or the AGENTS.md symlink:

agentctl run --name <container> --reset-config --cmd true
agentctl runtime reset-config codex

Next guides