Agent wählen und einrichten

Jede Box hat einen Agenten: Jeder neue Terminal-Tab startet ihn. Claude Code, Codex, OpenCode und Gemini CLI sind vorinstalliert und laufen ohne Rückfragen, neben Docker und einem kompletten Satz Entwickler-Tools.

Den Agenten für eine Box wählen

Den Agenten wählst du beim Anlegen einer Box unter 2. Agent. So änderst du ihn später:

1. Öffne die Box und bleib auf Übersicht.
2. Wähl im Panel Agent unter Jeder neue Tab startet einen neuen Wert.
3. Öffne einen neuen Tab. Die Änderung gilt für Tabs, die du ab jetzt öffnest. Offene Tabs behalten ihren Agenten.

Wechselst du zu einem Agenten mit einem anderen Abo-Platz, wird das alte Abo gelöst und die Rotation ausgeschaltet. Wie du Abos verbindest, steht unter Abos.

Was jede Box mitbringt

Neue Boxen laufen mit dem Image box-v3:

• Ubuntu 26.04 LTS, Docker Engine mit compose, Node 24, Python 3.14, git und tmux.
• Der Benutzer dev mit sudo ohne Passwort, in der Gruppe docker.
• Agent-CLIs: Claude Code, Codex, OpenCode, Gemini CLI, Happy und DeepSeek Harness (dsh), dazu die Wrapper claude-zai und claude-deepseek.
• Git und GitHub: gh, glab, git-lfs, delta.
• Suche und Daten: ripgrep, fd, fzf, jq, yq, bat, httpie.
• Datenbank-Clients: sqlite3, psql, redis-cli, mariadb.
• Paketmanager: pipx, uv, mise, bun, pnpm, yarn.
• Cloud: kubectl, helm, OpenTofu (tofu), AWS CLI v2.

Sprach-Toolchains sind nicht vorinstalliert, damit sie dir nicht die Disk wegfressen. Hol dir eine mit mise:

mise use -g go@latest

Die CLIs liegen in deinem Home-Ordner und aktualisieren sich deshalb ohne sudo. Eine Box, die vor box-v3 angelegt wurde, behält ihr älteres Debian-Image, bis du sie zurücksetzt. Die Zeile Image unter Einstellungen zeigt, welches eine Box nutzt.

Ohne Rückfragen

Eine Box ist eine Sandbox, die du zurücksetzen kannst, also läuft jeder Agent im Modus ohne Rückfragen. Ein Agent, der um 2 Uhr nachts auf ein Ja wartet, wird mit nichts fertig.

Einrichtungsscreens beim ersten Start und Fragen zum Vertrauen in Ordner sind schon beantwortet. Öffne einen Tab, und der Agent ist bereit für eine Aufgabe.

Gemeinsame Anweisungen in AGENTS.md

/etc/detachbox/AGENTS.md ist eine Anweisungsdatei, die jeder Agent liest. Sie erklärt den Agenten, wie Preview-URLs funktionieren und wie sie dir einen SSH-Befehl für rohe TCP-Ports geben. Sie ist in ~/.claude/CLAUDE.md, ~/.codex/AGENTS.md, ~/.config/opencode/AGENTS.md und ~/.gemini/GEMINI.md verlinkt.

Leg deine eigene Datei an einer dieser Stellen ab, und sie bleibt deine. detachbox fügt nur einen Verweis auf die gemeinsame Datei hinzu.

Claude Code auf Z.ai oder DeepSeek

claude-zai und claude-deepseek lassen Claude Code gegen den Anthropic-kompatiblen Endpunkt des Anbieters laufen, mit deinem eigenen API-Key. Jeder hat seinen eigenen Konfigurationsordner, ~/.claude-zai oder ~/.claude-deepseek, also bleibt dein Claude-Login in ~/.claude unberührt.

Leg den Key einmal in der Box ab, und jeder Tab nimmt ihn:

mkdir -p ~/.config/detachbox
read -rs -p 'Key: ' k && printf '%s\n' "$k" > ~/.config/detachbox/zai.key
chmod 600 ~/.config/detachbox/zai.key

Für DeepSeek schreibst du stattdessen ~/.config/detachbox/deepseek.key. ZHIPU_API_KEY oder DEEPSEEK_API_KEY zu exportieren funktioniert auch. Ohne Key sagt dir der Wrapper, wo er hingehört. Die eingebauten Z.ai- und DeepSeek-Provider von OpenCode schalten sich über dieselben Key-Dateien ein.

Box-Details in box.env

/etc/detachbox/box.env beschreibt die Box für jede Shell und jeden Agenten. detachbox schreibt die Datei beim Anlegen, Reset, Start und bei jeder Größenänderung neu, also bearbeite sie nicht.

Die Variablen laden in Login-, interaktiven und nicht interaktiven Shells, auch bei ssh <name>@ssh.detachbox.com <command>.

Eine Seite im Browser öffnen mit detachbox-open

detachbox-open <url> öffnet einen http- oder https-Link im Browser der Person am Terminal der Box. xdg-open, open und $BROWSER zeigen alle darauf. So landen Anmeldungen, die gh, Pythons webbrowser oder ein Agent startet, in deinem Browser.

Ein Link auf localhost:<port> der Box selbst wird zu ihrer Preview-URL. Andere Schemata wie file: werden abgelehnt. Was das Dashboard tut, wenn eine Seite ankommt, steht in der Terminal-Anleitung.

Einem Agenten einen Prompt geben mit detachbox-say

detachbox-say <tmux session> <text> liefert Text als neuen Prompt an den Agenten in diesem Tab. Es nutzt den eigenen Zustellweg des Agenten, nie Tastendrücke, also bleibt eine Zeile, die du gerade tippst, unversehrt. Es funktioniert mit Claude Code und Codex.

Der Server nutzt es, um „continue“ zu tippen, wenn ein Limit zurückgesetzt wird. Exit-Code 3 heißt: In dem Tab läuft kein Claude Code oder Codex, an den etwas gehen könnte.