Skip to content

README.md

Latest commit

 

History

History
195 lines (154 loc) · 10.7 KB

README.md

File metadata and controls

195 lines (154 loc) · 10.7 KB

Aetherion

A containerized development environment for AI coding agents.

Ships a Debian dev container preloaded with the bundled agent CLIs (Claude Code, Cursor Agent, GitHub Copilot CLI, Gemini CLI, OpenAI Codex, Pi, OpenClaw, Hermes), Neovim with LSP/DAP support, podman-in-podman, and toolchains for Python, Node, Go, Rust, and Ruby. Toolchains and agent binaries live system-wide in the image (under /opt and /usr/local), so image rebuilds deliver new versions to every workspace immediately. The aetherion launcher mounts the current directory inside the container and bind-mounts a host directory as $HOME — agent logins, shell history, and per-user tool state persist across sessions. Multiple independent namespaces (each its own $HOME) let you keep separate identities, model setups, or experiments side by side without cross-talk. A second CLI, conduit, ships alongside and points the agents at a model server running on your host (Ollama, LM Studio, or any OpenAI-compatible endpoint).

Install

uv tool install aetherion

(or pipx install aetherion)

To upgrade later:

uv tool upgrade aetherion

Quickstart

aetherion --build-image                  # one-time: build localhost/aetherion:dev
aetherion                                # first run auto-creates the 'default' namespace and enters

Inside the container, point agents at your host's model server:

conduit set endpoint lmstudio   # or `ollama`, or a full http(s):// URL
conduit launch pi               # pick a model in the TUI; pi launches against it

Using a local model server

The container itself does no inference — it's a dev environment. Run your model server on the host (LM Studio's local server, an ollama serve you already had, vLLM, llama.cpp's llama-server, anything that exposes OpenAI-compatible /v1/models) and conduit will wire the agent CLIs at it. The launcher sets up host-loopback networking automatically for both docker and rootless podman, so the host's 127.0.0.1:<port> is reachable from inside the container without reconfiguring the model server.

conduit set endpoint ollama                # → host's :11434
conduit set endpoint lmstudio              # → host's :1234
conduit set endpoint https://my.example    # any OpenAI-compatible /v1
conduit launch pi                          # arrow-key model picker → pi

Endpoint choice and last-used model per integration are stored at ~/.conduit/config.json and preserved across container sessions.

Publishing in-container ports

OpenClaw runs a gateway on port 18789 inside the container — but binds it to 127.0.0.1, which podman/docker port forwarding can't reach. Use --forward-openclaw to publish AND set up a loopback bridge in one shot:

aetherion --forward-openclaw                  # bind 127.0.0.1:18789 (host-local)
aetherion --forward-openclaw 0.0.0.0          # bind all interfaces, port 18789
aetherion --forward-openclaw 9999             # bind 127.0.0.1:9999  (remap host port)
aetherion --forward-openclaw 0.0.0.0:9999     # both: all interfaces + custom port
aetherion --forward-openclaw '[::1]:9999'     # IPv6 loopback, custom port

Then open http://<host-bind>:<host-port> on the host (container-side port is always 18789 — openclaw's own). For ports that already bind 0.0.0.0 inside the container, --forward CONTAINER_PORT (repeatable) is enough — no bridge needed.

What's in the container

Everything below is installed system-wide (under /usr/local/bin and /opt), so it's shared across every namespace and tracks the image version automatically. Per-user state — agent logins, npm globals, runtime go install binaries, nvim plugins, shell history — lives in the namespace's $HOME.

  • Launcher tooling: conduit (endpoint configuration + integration launcher; ships with aetherion)
  • Languages & runtimes: Python (system + uv), Node.js LTS + bun, Go, Rust, Ruby, C/C++ toolchain
  • Agent CLIs: Claude Code, Cursor Agent (agent), GitHub Copilot CLI, Gemini CLI, OpenAI Codex, Pi, OpenClaw, Hermes
  • Editor: Neovim with bundled LSPs (pyright, gopls, rust-analyzer, lua-language-server, typescript-language-server, vim-language-server) and DAPs (debugpy, delve, codelldb, js-debug-adapter). Plugins (Lazy.nvim-managed) auto-install on first nvim launch in each namespace.
  • CLI tools: git, podman, tmux, starship, ripgrep, fd, fzf, jq, yq, posting, openssh-client

Namespaces

A namespace is an independent host directory at ~/.aetherion/namespaces/<name>/ that the launcher bind-mounts as the container's $HOME. Everything that lives under $HOME inside the container — agent logins, runtime-installed npm/go/uv tools, nvim plugins once you've launched nvim, shell history, dotfile edits — is just files in that host directory and survives across sessions. Two namespaces share zero state: logging into Claude under work doesn't log you in under play.

The first time a namespace is used, the launcher seeds it from the image's /home/aetherion. The seed is small — just the skeleton dotfiles (.bashrc, .npmrc, .config/nvim/, .config/starship.toml) — because system tools and agent binaries live outside $HOME in the image. First entry is near-instant; first nvim launch in a namespace then runs Lazy's plugin install (a few minutes; cached afterward) and treesitter parsers compile on first file open.

aetherion                                 # auto-creates 'default' on first use, then enters
aetherion --namespace work --create-namespace
aetherion -n work                         # next launches into 'work'
aetherion --list-namespaces               # show what's been created and what image each came from
aetherion --reset-namespace               # nuke 'default' and re-seed from current image
aetherion -n work --reset-namespace --force

What updates when, and what doesn't

  • System tools (image-managed): aetherion, conduit, every agent CLI, every LSP/DAP, language runtimes. Rebuild the image and every existing namespace gets the new version on next launch — nothing to migrate.
  • Namespace contents (your state): agent logins, npm install -g packages, go install-ed binaries, nvim plugins, shell history, anything you touched inside. Stays put across image upgrades. To reset, use --reset-namespace.
  • Skeleton dotfiles (frozen at seed): .bashrc, .npmrc, .config/nvim/, .config/starship.toml. These are captured into the namespace at seed time and don't refresh when the image changes — if a new image ships a .bashrc you want, the launcher prints a one-line drift notice on launch suggesting aetherion --reset-namespace (which drops everything else in the namespace too, so use with care).

Migrating from older aetherion

A prior install's ~/.aetherion/data/ (the per-agent layout) is auto-migrated into the default namespace on next launch: the launcher seeds default from the current image, overlays the legacy per-agent dirs (.claude/, .gemini/, go/, etc.) on top so existing logins win, and renames the old directory to data.migrated-YYYYMMDD as a safety net. Delete the safety copy once you've confirmed everything works.

Flags

flag purpose
-n, --namespace NAME Namespace whose $HOME to mount. Default: default (auto-created on first use). Other namespaces error if they don't exist; pair with --create-namespace. Names: letters, digits, dot, underscore, dash (no leading dot).
--create-namespace Create the namespace selected by -n if it doesn't exist (seeded from the current image). No-op when it already exists. Not needed for default. Combines with launch.
--list-namespaces List existing namespaces with the image digest each was seeded from, then exit.
--reset-namespace Delete the namespace selected by -n and re-seed from the current image, then exit. Drops every in-namespace customization. Confirms unless --force is also passed.
--force Skip the confirmation prompt for --reset-namespace.
-e, --env NAME=VALUE Set a container environment variable. Repeatable. Quote at the shell for values with spaces: --env 'NAME=has spaces'. A bare --env NAME inherits from the host environment.
--forward [ADDR:[HOST_PORT:]]CONTAINER_PORT Publish a container port (podman/docker -p semantics). Repeatable. Forms: PORT, HOST:CONTAINER, ADDR:HOST:CONTAINER, :HOST:CONTAINER, [::1]:HOST:CONTAINER. Default host bind is 127.0.0.1. Services that bind 127.0.0.1 inside the container won't be reachable through this alone — use a --forward-<agent> alias.
--forward-openclaw [ADDR][:PORT] Convenience alias for OpenClaw's gateway (container port 18789). Publishes the port AND sets up a loopback bridge so the publish actually reaches it (openclaw binds 127.0.0.1 inside the container). Bare = 127.0.0.1:18789; otherwise accepts ADDR, PORT, ADDR:PORT, :PORT, [::1]:PORT.
--image REF Image ref to run, and to tag when building. Default: localhost/aetherion:dev.
--build-image Build the image and exit. Does not launch the container.
--build-dir PATH Build context directory. Defaults to the Dockerfile bundled with the launcher.
--refresh-layers Discard the runtime's build cache for this build (--no-cache). Use to refresh anything pinned by an intermediate layer's snapshot: apt mirrors, the Node.js LTS tarball, the system npm install of agent CLIs, the cursor.com/install script, hermes-agent's PyPI release, the gopls/dlv go install. Without it you stay on whatever was current the first time the layer was built; with it every upstream gets re-fetched. Only meaningful with --build-image.
--extract PATH Copy the bundled Dockerfile and skeleton/ to PATH and exit.

AETHERION_CONTAINER_RUNTIME=docker overrides runtime auto-detection (podman is preferred when both are available).

Customizing the image

The launcher ships its own Dockerfile and skeleton tree inside the Python package. To fork them:

aetherion --extract ~/my-aetherion
$EDITOR ~/my-aetherion/Dockerfile
aetherion --build-image --build-dir ~/my-aetherion --image my:tag
aetherion --image my:tag

Development

git clone https://github.com/samintheshell/aetherion
cd aetherion
uv sync
uv run aetherion --help

Build and publish the Python package with the included Makefile:

make            # show available targets
make build      # produce sdist + wheel in dist/
make publish    # upload dist/* to PyPI (UV_PUBLISH_TOKEN required)

The container image itself has uv plus the standard CPython toolchain installed, so you can also run make publish from inside an aetherion shell if you prefer keeping credentials in the container.