Towline

An open-source toolkit that lets AI coding agents (Claude Code, Cursor, Codex, etc.) deploy and operate Docker containers on Portainer-managed infrastructure. It consists of four parts:

1. towline CLI — scaffolds a new project: creates a Portainer team, scoped API key, container stack, agent config, compose files, and git repo.
2. towline-mcp — an MCP server (Go binary) that runs per-project, giving the agent 10 operational tools (health, logs, env vars, domains, scale, exec) plus upstream Portainer stack CRUD and Docker proxy, all scoped to a single stack.
3. DevOps skill — a markdown file (skills/towline-devops.md) installed into every project that teaches the agent how to use the tools: deployment workflows, debugging patterns, rollback procedures, and the tier/approval model.
4. Template packs — bundles of compose files, domain-specific agent skills, and additional MCP configs. The ai-stack pack ships Ollama + Open WebUI with an AI operations skill; the n8n pack ships n8n + PostgreSQL with a workflow operations skill. Compose templates (api, web-app) are also available without pack-level skills.

Who this is for

You run Portainer (self-hosted or cloud) and want AI agents to deploy containers without giving them admin access to your entire infrastructure. Towline creates a per-project boundary: dedicated Portainer team, scoped API key, single-stack MCP server. Even if the agent misbehaves, Portainer rejects anything outside its assigned scope.

What a project looks like

~/projects/my-app/
├── .claude/settings.json   # MCP config → launches towline-mcp
├── CLAUDE.md               # Agent instructions for this project
├── docker-compose.yml      # From template or pack
├── .env.example
├── skills/
│   ├── towline-devops.md   # Base operational skill
│   └── ai-ops.md           # Pack skill (if using ai-stack)
└── .git/

The skills are not documentation — they are agent training. The DevOps skill teaches deployment workflows, debugging procedures, and how to use the approval system. Pack skills add domain knowledge on top (e.g., the ai-stack skill teaches how to pull Ollama models and manage Open WebUI).

Dev and prod tiers

In dev tier, the agent has full autonomy — every tool call executes immediately. In prod tier, reads and operational actions (health, logs, start, scale) are instant, but mutations (deploy, env changes, delete, exec) require a single-use approval token. The token is bound to the specific tool and arguments — it can't be reused with different parameters.

Step by step

1. Install

Installs two binaries: towline (CLI) and towline-mcp (MCP server) to /usr/local/bin. Run towline help to see all commands.

2. Connect to Portainer

Interactive wizard. Asks for your Portainer URL, admin API key, and default environment ID. Saves to ~/.towline/config.yaml. Only needed once per machine.

3. Create a project

Creates a Portainer team, scoped API key, container stack, MCP server config, DevOps skill, compose file, and git repo. The project directory is ready for your agent.

4. Start your agent

The agent reads .claude/settings.json which launches towline-mcp automatically. It picks up the DevOps skill from CLAUDE.md, gets access to the MCP tools, and can deploy, debug, scale, and operate within the isolated stack. For non-Claude agents, the MCP config is also generated for Cursor, Gemini CLI, etc.

5. Manage projects

towline list                 # see all projects
towline status my-api        # stack state, tier, endpoint
towline promote my-api       # move from dev to prod tier
towline rotate-keys my-api   # rotate API key
towline destroy my-api       # tear down everything

Requirements

• Portainer v2.28+ with API access (self-hosted or Portainer Cloud)
• Docker on the container host
• An MCP-compatible agent (Claude Code, Cursor, Codex, Gemini CLI, Windsurf)