Runabout #
Runabout gives agents persistent Common Lisp REPLs. It stores conversations in SQLite and agent state in SBCL core images. It supports multiple model providers, inter-agent messaging, delegation, scheduling, and MCP.
Agents inherit the Runabout account's file and network access. User installs do not sandbox agents. Debian system services use a restricted service account.
Build and install #
Runabout requires Linux, SBCL, GNU Make, libcurl, SQLite with FTS5, PCRE2, and zstd. Calendar schedules also require systemd's private shared library and timezone data.
Debian 13:
sudo apt install sbcl make libcurl4t64 libsqlite3-0 libpcre2-8-0 libzstd1 libsystemd-shared tzdata
make
Fedora: sudo dnf install sbcl make libcurl sqlite-libs pcre2 libzstd
Arch: sudo pacman -S sbcl make curl sqlite pcre2 zstd
The build produces three executables in dist/:
| Program | Purpose |
|---|---|
runabout |
Harness, database, agents, and provider connections |
runabout-repl |
Agent Lisp process |
runabout-web |
HTTP server and browser client |
Keep runabout and runabout-repl together. Runabout supports
SBCL on x86-64 and ARM64 Linux; it does not support other Lisp
implementations or static binaries.
For Nix, enable nix-command and flakes, then run nix develop path:.
or nix build path:.. The build runs the Lisp checks and includes
runtime libraries. Install it with nix profile install path:.; see
Operations for service setup.
Configure and start #
The harness reads $XDG_CONFIG_HOME/runabout/config.sexp, normally
~/.config/runabout/config.sexp. make install creates an example config
on first use and stops so you can edit it. A minimal connection is:
(:provider :generic
:endpoint "https://api.example.com/v1/chat/completions"
:api-key "your-api-key"
:model "your-model-id"
:models (("your-model-id" :context 65536 :tools t :vision nil)))
The model must support function calling. Use :generic for compatible
chat-completions APIs or :deepseek, :mimo, :kimi, :qwen, or
:glm for their dialects. See Configuration for
discovery, capabilities, meters, budgets, prompts, and handoff.
After saving the config, run:
make install
This installs user services, starts the workspace, and prints the login URL.
The first start creates an agent named leah. Closing the browser does not
stop agents. Print the URL again with runabout-web --print-url.
Common service commands:
systemctl --user status runabout.socket runabout.service runabout-web.service
systemctl --user restart runabout.target
systemctl --user stop runabout.target
journalctl --user -u runabout.service -u runabout-web.service -n 50
Enable lingering to keep agents running after logout:
sudo loginctl enable-linger "$USER"
See Operations for backup, recovery, upgrades, service overrides, Nix profiles, Debian packages, and remote access.
Data #
| Data | Default path |
|---|---|
| Configuration | ~/.config/runabout/config.sexp |
| Database | ~/.local/share/runabout/runabout.db |
| Agent cores | ~/.local/share/runabout/cores/ |
| Attachments | ~/.local/share/runabout/files/ |
| Login key | ~/.local/state/runabout/web-token |
| Logs | ~/.local/state/runabout/logs/ |
Runabout honors absolute XDG_CONFIG_HOME, XDG_DATA_HOME, and
XDG_STATE_HOME. The socket uses XDG_RUNTIME_DIR or the state directory.
Stop the harness before backup. Keep the database, attachments, cores,
executables, and adjacent repl-bundle/ tree together. A core requires the
bundle version paired with the executable that restores it.
The browser listens on localhost by default. Remote access requires an SSH tunnel or HTTPS proxy. Anyone with the login URL can control every agent.
Development #
make test-unit # Lisp unit checks
make test-lisp # build and process checks
make test-gui # browser logic checks
make test # full suite
Tests use temporary data and local mock providers. See Contributing and the MCP reference.