Getting Started¶

Prerequisites¶

Docker installed and running
An AI coding agent installed on your host (Claude Code, Gemini CLI, or Codex) — Asylum seeds its config from your host installation

Install Asylum¶

curl -fsSL https://raw.githubusercontent.com/inventage-ai/asylum/main/install.sh | sh

This detects your OS and architecture and downloads the correct binary.

First Run¶

cd your-project/
asylum

On the very first run, Asylum:

Builds the base image (asylum:latest) — a full dev toolchain with all three agent CLIs, language runtimes, and tools. This takes ~5 minutes and is cached for all projects.
Seeds agent config — copies your host agent configuration (e.g., ~/.claude) to ~/.asylum/agents/claude/. This is a one-time copy; the asylum copy is independent after seeding.
Starts a container — mounts your project directory, caches, and agent config, then launches the agent.

Subsequent runs start in seconds since the image is cached.

What Happens Inside¶

When the container starts, you get:

Your project mounted at its real host path (not /workspace) — absolute paths and git worktrees work correctly
Agent config, SSH keys, git config, and shell history mounted from ~/.asylum/
Package caches (npm, pip, maven, gradle) persisted in named Docker volumes
A full dev environment: Python 3 + uv, Node.js LTS + fnm, Java 17/21/25 + mise, build tools, and more

Choosing an Agent¶

asylum              # Claude Code (default)
asylum -a gemini    # Gemini CLI
asylum -a codex     # Codex

Each agent runs in YOLO mode by default (auto-approve all actions). Agent config is stored separately per agent in ~/.asylum/agents/<agent>/.

Project Configuration¶

Create a .asylum file in your project root to customize the environment:

agent: gemini

kits:
  java:
    versions: ["17"]
  node:
    packages:
      - "@anthropic-ai/claude-mcp-server-filesystem"

ports:
  - "3000"
  - "8080:80"

env:
  DEBUG: "true"

See Configuration for all options, and Kits for available language and tool kits.

SSH Setup¶

To use git over SSH inside containers:

asylum ssh-init

This creates an Ed25519 key pair in ~/.asylum/ssh/. Add the public key to GitHub/GitLab. The keys are mounted into every container automatically.

Next Steps¶

Commands — all available commands and flags
Configuration — layered YAML config system
Kits — language and tool kits
Concepts — how images, mounts, and sessions work