AI Playground

A playground is a safe environment, often with a fence around it, perfect for letting AI agents play while you keep an eye on them.

aip is a command-line tool that runs AI coding agents like OpenCode or Claude Code inside a secure systemd container, giving them the freedom to work without risking your host system. The container can be started within a second as it is lightweight and requires no daemon, making it the perfect fit for quickly spinning up an isolated environment.

Requirements

• Fedora (other distros can be contributed)
• Linux with systemd >= 258 (systemd-contianer)
• Usermode

Installing

See INSTALL.md for build and installation instructions.

Usage

Every playground needs a bit of setup before the kids can go wild.

Setting the ground rules

First, lay down the ground rules. Create a configuration file:

aip config --create

This drops a default config into ~/.config/ai-playground/config.toml. Open it up and make sure your AI agent gets the keys it needs to do its job — API tokens don't jump over fences on their own:

[env]
pass_through = ["ANTHROPIC_API_KEY"]

Building the playground

With the rules in place, it's time to build the actual playground.

Install the root filesystem and the AI tool:

aip init

This sets up a fresh Fedora container and drops your chosen AI tool into it. Think of it as pouring the sandbox and bolting down the swings.

Getting a visitor pass (optional)

If your agent needs to talk to Google Cloud, you can hand it a temporary visitor pass. This spins up a shell, installs the gcloud CLI just long enough for you to authenticate, and cleans up after itself:

aip shell --gcloud-init

Opening the gates

Everything is ready — time to let the AI out to play:

aip run

Or just:

aip

Your project directory is mounted into the container and the agent gets to work while safely fenced in.

Standing at the gate

Sometimes the AI needs to reach outside the fence — run cargo build on the host, invoke podman, or call other tools that aren't available inside the container. The gate lets you supervise every request:

In one terminal, start the gatekeeper:

aip gate

This opens a TUI where you can approve or deny each command the AI tries to run on the host. In another terminal, launch the agent with the commands you want to proxy:

aip run --host-exec cargo podman rustfmt

Inside the container those commands become transparent proxies — when the AI runs cargo build, the request appears in the gate TUI for your approval. You can allow it once, allow it for the whole session, or deny it.

Here be dragons! Once a command slips through the gate it's outside the fence — running with your full host privileges, no sandbox, no safety net. Only open the gate for commands you understand and trust.

Peeking over the fence

Want to see what's going on inside? Drop into an interactive shell for a look around:

aip shell

Maintaining the grounds

Playgrounds need maintenance. Keep packages and tools fresh with:

aip update

Features

• Lightweight containers - a toddler can carry it
• Git worktree support - everyone loves trees
• Easy to set up and keep up to date - just aip init and aip update
• Visitor passes for Google Cloud - aip shell --gcloud-init sets up Vertex AI access
• Host command gatekeeper - aip gate lets you approve or deny host commands from inside the container
• Multiple AI tools supported - contributions welcome

Documentation

For detailed usage and configuration reference, see the manpages:

• aip(1) - command-line usage
• aip-gatekeeper(1) - The gatekeeper TUI
• aip-host-exec(1) - host-side command proxy
• ai-playground.toml(5) - configuration file

Design

For a look under the hood, how containers are built, how config layering works, and how the gate mechanism operates, see DESIGN.md.

Contributing

AI Playground is an open source project — the gates are always open. Feel free to use it, share it, and if you want to help build new swings, just open a pull request or get in touch.