Connect your agent

ownpaas gives your coding agent two things:

1. The environment for its usual tools. With HCLOUD_ENDPOINT and HCLOUD_TOKEN set, the agent uses the hcloud CLI or Terraform against the lab; with a cluster’s kubeconfig it uses kubectl and Helm. Agents already know these tools, so there is nothing new for them to learn.
2. A small MCP server for what those tools cannot do: projects, reset, checkpoints and the cost estimate.

The MCP server is thin on purpose. It has no generic passthrough and no resource listing; building the infrastructure stays with the tools above.

Add ownpaas to your agent

In the menu bar choose Add MCP server to…, or open Settings › Agents, and pick the agent. The app shows the entry it will write, with the tokens masked, and writes it only after you confirm. It merges the entry into the existing file and keeps a backup next to it (<file>.ownpaas-backup-<timestamp>).

Agent	Where the entry goes
Claude Code	claude mcp add --scope user when the claude command is found, otherwise mcpServers in ~/.claude.json
Cursor	~/.cursor/mcp.json
Codex	[mcp_servers.ownpaas] in ~/.codex/config.toml (other tables stay as they are)
Claude Desktop	mcpServers.ownpaas in ~/Library/Application Support/Claude/claude_desktop_config.json
any other MCP client	Copy JSON gives you the entry to paste

Restart the agent (or start a new session) so it loads the server. Claude Desktop reads its file only at launch: quit it and open it again. Claude Desktop is a chat app without a shell, so it gets the ownpaas tools but cannot run hcloud, Terraform or kubectl.

One project, or a project per session

The app asks which access the agent gets.

• One project (the default and the safer choice). The agent gets a token for one project, named after the agent (claude-code, cursor, codex). It can do anything inside that project and nothing outside it.
• A project per session. The MCP server creates a new project for each agent session and deletes or keeps it at the end. For this the agent gets an agent token: it can create projects and use the projects it created, and nothing else. The lab’s admin token stays with the app.

Each agent’s actions show up under its token name in the project’s Activity, so you can see which agent did what.

The MCP tools

Tool	What it does
create_project, delete_project	create a project and return its endpoint and token; delete a project with everything in it (project per session only)
reset_project	delete every resource of the project and wait until it is empty
create_checkpoint, list_checkpoints, restore_checkpoint, delete_checkpoint	checkpoints
estimate_cost	what the project would cost per month in the cloud, item by item
export_to_hetzner	a Terraform configuration that recreates the project’s servers, networks and load balancers in Hetzner Cloud

Give the agent a cluster

For a Kubernetes cluster, open the cluster’s Access tab and choose Hand to Agent. The app writes that cluster’s kubeconfig to a file only you can read, and copies export KUBECONFIG=… for the agent’s shell. The management cluster’s kubeconfig is never handed out, because it can read every cluster’s cloud token. See Kubernetes clusters.

Stop an agent

Settings › Agents has a kill switch per agent: it revokes the tokens the agent was given, and every token they created, and powers off the servers of its projects. The projects and their checkpoints stay.

What the agent never gets

The token of your cloud account. Agents work in the lab; Move to Cloud runs in the app, with your own token from the Keychain.

Prompts that work

Agents do better when they know about checkpoints. A line like this in your project’s agent instructions (CLAUDE.md, AGENTS.md, Cursor rules) is enough:

Infrastructure runs in an ownpaas lab. Before a change that could break the
setup, call create_checkpoint with a short name. If the change breaks it,
call restore_checkpoint instead of repairing by hand.