Zephira

Zephira is a coding-agent harness, written in Ruby, for experimenting with high-autonomy workflows, sandboxed execution, and agent behavior patterns.

It runs in your terminal and is designed around broad agent autonomy inside a constrained development environment. The agent can read files, edit code, run commands, search, make HTTP requests, and iterate freely within its workspace, while Docker or Podman keeps that activity separated from the host system by default.

Zephira's goal is to explore what becomes possible, useful, and risky when a coding agent can operate with broad autonomy inside a disposable development sandbox.

Zephira is useful for experimenting with:

• high-autonomy coding-agent workflows
• self-directed implementation loops
• agent-managed memory, context, and working state
• sandboxed development environments
• Ruby-based agent architecture

It is best thought of as a small, inspectable research and development harness rather than a polished end-user coding assistant.

1. Install Docker or Podman — required for the sandbox.

   • Docker: https://docs.docker.com/get-docker/
   • Podman: https://podman.io/getting-started/installation

2. Install the gem:

   gem install zephira

3. Run it from any project directory:

   zephira

   On first run, Zephira launches an onboarding wizard that prompts for your OpenAI API key and writes it to ~/.zephira.yml (with 0600 permissions). You can also set ZEPHIRA_API_KEY in your environment to skip the wizard entirely. To target a different OpenAI-compatible endpoint, set ZEPHIRA_BASE_URL alongside your key.

• Interactive terminal chat loop with per-session token-budget tracking and automatic history compaction
• Built-in slash commands: /help, /about, /model, /history, /compact, /clear, /reload, /bye
• First-run onboarding wizard that captures your API key the first time you launch — no manual ~/.zephira.yml editing required
• Plugin-style tool system — drop a file in lib/zephira/tools/ and it is auto-loaded:
  • file I/O: read_file, update_file, delete_file, list_directory
  • search: code_search (ripgrep-backed), web_search (Brave Search API)
  • execution: shell, http_request
  • persistent memory: memory_read, memory_write, memory_list, memory_delete
• Concurrent execution of read-only tool calls in a single turn (mutating tools still run sequentially in declared order)
• Pluggable model + backend layer — register a new model by dropping a file in lib/zephira/models/; backends bind per model class
• OpenAI-compatible backend out of the box; structured to add provider-specific backends without forking the core loop
• Docker or Podman sandbox enabled by default; --dangerously-skip-sandbox to opt out
• Persistent session log + conversation history under .zephira/ in each project
• ~95% line coverage on a focused RSpec suite

zephira              # start in the current directory
zephira --help       # CLI help
zephira --version    # installed version
zephira --dangerously-skip-sandbox  # run without container isolation (your filesystem is exposed)

git clone https://github.com/aarongough/zephira.git
cd zephira
bundle install

Requirements: Ruby 3.2+, Bundler, Docker or Podman (for sandboxed execution).

The first time you run Zephira without an API key configured, the onboarding wizard prompts for one and writes it to ~/.zephira.yml. You can also configure Zephira manually:

• environment variables
• .zephira.yml in the current project
• ~/.zephira.yml in your home directory

Environment variables take precedence. Setting ZEPHIRA_API_KEY in your environment also skips the onboarding wizard, which is the recommended path for CI and other non-interactive contexts.

Example configuration:

ZEPHIRA_API_KEY: "openai_API_KEY_HERE"
ZEPHIRA_BRAVE_SEARCH_API_KEY: "your_brave_api_key_here"

• ZEPHIRA_API_KEY — API key for the selected LLM backend
• ZEPHIRA_MODEL — model name to use
• ZEPHIRA_BASE_URL — base URL for OpenAI-compatible APIs
• ZEPHIRA_BACKEND — backend adapter identifier
• ZEPHIRA_BASE_IMAGE — base container image for sandbox execution
• ZEPHIRA_BRAVE_SEARCH_API_KEY — required for the web search tool
• ZEPHIRA_SANDBOX — internal/advanced flag to disable sandboxing

By default, Zephira runs inside a Docker or Podman container.

When sandboxing is enabled, Zephira re-executes itself inside the container and mounts your current project into /workspace. This gives the agent broad access to the working tree while keeping execution separate from the host filesystem.

This is useful containment for local development and experimentation, but it should not be treated as a complete security boundary. The agent can still modify files, run commands, make network requests, and interact with anything available inside the workspace.

You can bypass sandboxing with:

zephira --dangerously-skip-sandbox

Use that only if you understand the risks.

Inside Zephira, you can use slash commands:

• /help — show available commands
• /about — show project information
• /model — list available models
• /model set MODEL_NAME — switch models for the current session
• /history — print conversation history
• /compact — manually compact the conversation history
• /clear — clear the screen
• /reload — re-execute the agent process to pick up local code changes (conversation history is preserved)
• /bye — exit the session

To change your API key after onboarding, edit ~/.zephira.yml directly on the host, or delete it and re-launch to trigger the wizard again.

This repository currently includes model definitions for:

• gpt-4.1
• gpt-4.1-mini
• gpt-5.4
• gpt-5.5
• gpt-o4-mini
• claude-3.5-sonnet
• llama4

The exact names available in the running app are determined by the model classes in lib/zephira/models.

Zephira includes tools for:

• read_file
• update_file
• delete_file
• list_directory
• code_search
• shell
• http_request
• web_search
• memory_write
• memory_read
• memory_list
• memory_delete

These tools allow the agent to inspect the project, modify files, run commands, query APIs, and maintain lightweight persistent memory.

exe/                     Executable entrypoint
lib/zephira/             Core application code
lib/zephira/models/      Model definitions
lib/zephira/tools/       Tool implementations
lib/zephira/commands/    Slash commands
lib/zephira/completions/ Readline completions
spec/                    Test suite
Dockerfile               Sandbox/runtime image

Install dependencies:

bundle install

Run the test suite:

bundle exec rspec

Run linting:

bundle exec standardrb --fix

For an isolated dev environment that mirrors the shipped sandbox image, the bin/ directory provides helper scripts. All three rebuild the zephira-dev image first (Docker caches layers, so this is a no-op after the first run).

• bin/docker-build — build the zephira-dev image from the current working tree.

• bin/docker-zephira — launch Zephira inside the container, running against the mounted working tree (bundle exec ruby exe/zephira). Use this when iterating on the agent itself.

• bin/docker-shell [command] — start an interactive bash inside the container, or run an arbitrary command. Useful for running specs or linting against the containerized Ruby:

  bin/docker-shell                                # interactive shell
  bin/docker-shell 'bundle exec rspec'            # run the suite in-container
  bin/docker-shell 'bundle exec standardrb --fix' # lint in-container

Both runner scripts mount the current directory at /workspace, run as the host UID/GID, and mount ~/.zephira.yml and ~/.zephira/ into the container so configuration and history persist across runs.

bin/docker-zephira runs the onboarding wizard as a host-side preflight before launching the container, so first-run users get the same prompt-and-write-to-~/.zephira.yml experience they'd get with a normal gem install zephira invocation.

While inside a running Zephira session started this way, the /reload slash command re-executes the agent process — picking up edits to lib/zephira/** without rebuilding the image or losing conversation history (which is persisted to .zephira/history.jsonl). This is the fastest inner loop for iterating on agent code.

Zephira favors:

• autonomy inside a constrained environment
• clarity over complexity
• small, readable components
• hackability and extension
• realistic terminal-first workflows
• sandboxed local agent execution

It is best thought of as a lightweight coding assistant and learning-oriented agent framework, not a full enterprise platform.

Zephira stores session information under .zephira/ in the current project directory, including logs and conversation history. This makes sessions project-local and easy to inspect.

Released under the MIT License.

See:

license.txt

Aaron Gough

Project home: https://github.com/aarongough/zephira