▗▟█▙▖ ▗▟█▙▖ ▐██▘ ▐██▌ ▐███████▘ ▄▟██████▙▄
█▓███ ███▓█ ▝██ ██ ▐██ ▄█▛▀ ▝▜██▄
▝▀█▀▘ ▝▀█▀▘ ██ ██ ▐██ ▟█▛ ▝██▌
██ ██ ▐██▄▄▄▄▄ ██▘ ▐██
██ ██ ▐██▀▀▀▀▀ ██▌ ▐██
▗▟█▙▖ ██ ██ ▐██ ▜██▖ ▟█▌
▓████ ▜█▙▖ ▄▟██ ▐██ ▀██▄▖ ▄██▀
▝▀█▀▘ ▀█████▛▀██▌ ▐██▖ ▀▜██████▛▀
Run AI agents for your team on your own infrastructure.
The same runtime powers UFO's hosted service.
Self-host · How it works · Use hosted · Security model · Extend it · Spec · Documentation · Blog
UFO is an open source runtime for AI agents. Team members give agents work in chat. Agents can read files and run commands to complete that work.
UFO's hosted service runs this code. You can also run it yourself with your own
model keys. The ufo terminal client connects to either. This repository contains the server,
client, SDK, and extensions.
To host UFO yourself, run one process on SQLite and local files, with no Docker. Install uv, then:
make install
cp .env.template .env # set UFO_ANTHROPIC_API_KEY and UFO_OPENAI_API_KEY
make build
make init EMAIL=email@work.com
make servemake init creates the workspace with you as admin and writes a CLI token to ~/.ufoctl/token.
make serve listens on http://localhost:8710. In a second terminal:
mkdir -p ~/.ufo && install -m 600 ~/.ufoctl/token ~/.ufo/credentials
echo http://localhost:8710 > ~/.ufo/workspace
./client/target/debug/ufo "what can you do?"The agent loop and conversation run in ufoctl serve in both modes. The flag selects where the
agent reads and edits files and runs commands when you start a conversation:
A resumed conversation keeps the execution location it already has. See client/README.md for
client options.
.env refuses the bare names ANTHROPIC_API_KEY and OPENAI_API_KEY, because every tool that
reads .env gets all of its values.
Postgres
make db starts Postgres on 127.0.0.1:5541 (user, password, and database ufo). Before
make init, write a ufo.toml that points at it:
make db
uv run python -c 'from ufo.cli import DEFAULT_CONFIG; print(DEFAULT_CONFIG, end="")' \
| sed 's#sqlite+aiosqlite:///ufo.db#postgresql+asyncpg://ufo:ufo@127.0.0.1:5541/ufo#' > ufo.tomlBrowser tools on macOS
ufo --remote browser tools drive Chrome's headless shell from the PATH of make serve. Put its
directory on the PATH, not a symlink to the binary:
npx playwright@$(uv run python -c 'from ufo.sdk.sandbox import PLAYWRIGHT_VERSION; print(PLAYWRIGHT_VERSION)') install chromium-headless-shell
PATH="<dir>/chrome-headless-shell-mac-arm64:$PATH" make serve<dir> is the location Playwright reports (--dry-run prints it). Intel Macs use
chrome-headless-shell-mac-x64.
Sites and the session debugger
A pack names the extensions a deploy activates. assistant is the default.
Create a workspace with your work email. The hosted service runs
agents and scheduled tasks on UFO's infrastructure and provides model access. Your team can
use the web app or Slack without running ufoctl serve or setting model API
keys.
Connect Slack during workspace setup. To use the same workspace from your terminal on macOS or Linux, install the client:
curl -fsSL https://ufo.ai/ufo | shRun ufo and sign in. Start it from a directory to let the agent work on its files, or run
ufo --remote to use the hosted sandbox. The table in Quick start compares the two
modes. See the terminal guide for more detail.
An extension is a Python package that imports only ufo.sdk and declares one entry point:
[project.entry-points."ufo.extension"]
acme = "ufo_ext_acme.manifest:manifest"extensions/sample exercises every manifest point. ufoctl ext search | install | remove manages
installed extensions. spec.md §Extension system lists each point's contract.
ufoctl bundle freezes a deploy — image recipe, client, pinned config, lockfile — into one
artifact. It serves a single node, an on-prem install, or a fleet; scale-out adds instances,
Postgres, S3, and the Redis hub.
make lists every target. make check runs the static gates, make test the parallel suite,
make test-one FILE=… one file, and make test-integration the serial and Docker pass. make db
starts the Postgres and Redis they use. Browser tests need Chrome for Testing:
npx playwright@$(uv run python -c 'from ufo.sdk.sandbox import PLAYWRIGHT_VERSION; print(PLAYWRIGHT_VERSION)') install chromium chromium-headless-shellRead spec.md before you propose a structural change, and AGENTS.md before you open a pull
request.
Apache-2.0. See LICENSE and NOTICE.