opsdeck

opsdeck is an AI agent harness for infrastructure. It works like Claude Code or opencode, but its world is servers, networks and VPNs, containers, clusters and logs instead of a code repository. It is also a complete local workbench that is just as useful without AI. Everything runs on your computer: a desktop app for Windows, macOS and Linux, or opsdeck serve with the UI in your browser.

Install

Download the latest release for your system from Releases:

System	File
Windows 10/11 (x64)	opsdeck-<version>-windows-x64-setup.exe (or the portable .exe)
macOS 12+ (Apple silicon and Intel)	opsdeck-<version>-macos-universal.dmg
Debian, Ubuntu (x86_64)	opsdeck_<version>_amd64.deb
Fedora, RHEL, openSUSE (x86_64)	opsdeck-<version>-1.x86_64.rpm
CLI only (any of the above, plus Linux arm64)	opsdeck-cli-<version>-<os>-<arch>

Or let a script pick the right file, check its checksum and install it:

# Linux and macOS
curl -fsSL https://vahidid.github.io/opsdeck/install.sh | sh
# only the CLI, into ~/.local/bin
curl -fsSL https://vahidid.github.io/opsdeck/install.sh | sh -s -- --cli

# Windows (PowerShell)
irm https://vahidid.github.io/opsdeck/install.ps1 | iex

The builds are not code-signed yet. The first time you open opsdeck on macOS, right-click the app and choose Open. On Windows, SmartScreen asks once: choose More info → Run anyway.

Updates: opsdeck checks GitHub for new releases and shows an Update available box in the sidebar. One click downloads the update and checks it against the release's SHA256SUMS.txt and that file's signature by the opsdeck release key (how to check it yourself), then installs it the way you installed opsdeck and restarts:

• the installer on Windows
• the app in place on macOS
• the .deb or .rpm package on Linux, after your password
• the binary itself for the CLI

You can turn the check off, or check now, under App settings → Updates.

Use it from Claude Code, Codex, Cursor…

opsdeck is an MCP server for the agent you already use. Claude Code, Codex, Cursor, Gemini CLI, VS Code or any MCP client gets a workspace's tools: SSH through its VPNs and jump hosts, Docker, Kubernetes, databases, logs, metrics, DNS, certificates and deployments. opsdeck keeps the credentials and checks, redacts and logs every call. A change waits until you approve it in opsdeck.

1. In opsdeck: App settings › Agent access › Connect an agent. Pick the workspace and a mode (Read-only, Ask or Auto). opsdeck shows an access key and the exact setup for your agent.

2. Add the server to your agent, e.g. for Claude Code:

   claude mcp add --scope user --transport http opsdeck-acme http://127.0.0.1:7788/mcp/ext \
     --header "Authorization: Bearer odk_…"
   

   Over stdio instead: OPSDECK_TOKEN=odk_… opsdeck mcp.

3. Install the skill, which teaches the agent how to work through opsdeck (look first, expect approvals, leave a report):

   # Claude Code: the plugin brings the skill and the MCP server, and asks for the key
   /plugin marketplace add vahidid/opsdeck
   /plugin install opsdeck@opsdeck
   
   # or for any agent
   opsdeck skill install claude-code   # or codex, gemini, cursor, dir --dir PATH
   

The agent's calls show up in a session of their own on the Agent page, where you approve them. The setup for Codex, Cursor, Gemini CLI and VS Code, the modes and the security model are in docs/agents.md.

Features

• Workspaces — one per project: hosts, groups, VPN profiles and proxies, jump hosts, web panels, Git repos, domains, TLS certificates, deployment platforms, databases, Kubernetes clusters, docs and runbooks. Plain YAML + Markdown, git-friendly, never contain secrets.
• Vault — local, encrypted (Argon2id → XChaCha20-Poly1305, a separate key per workspace): SSH keys (generate/import), logins with TOTP, API tokens, kubeconfigs, VPN configs, certificates, secret files. Secrets are used by opsdeck, never shown to the agent.
• VPNs — WireGuard, Tailscale/Headscale, NetBird, OpenVPN, Cisco AnyConnect, ocserv, FortiGate, GlobalProtect, Pulse, F5 and SOCKS, each in userspace mode (network stack inside opsdeck: no root, many at once, optional local SOCKS5 proxy for other apps) or system mode (TUN with system routes, through sudo/pkexec). A VPN page per workspace with connect/disconnect, login links, logs and live status. Single sign-on (SAML via Entra ID, Okta, …) for AnyConnect, GlobalProtect and FortiGate without copying cookies: opsdeck shows the login and takes the session itself. One-time codes by SMS or email (FortiGate) are asked for in the app, or forwarded from your phone, and a dropped tunnel reconnects without a new code — see docs/vpn.md.
• Git repositories — connect your GitHub / GitLab account once under Connectors (github.com, GitHub Enterprise, gitlab.com, self-hosted GitLab; your gh/glab login, browser sign-in or a token from a pre-filled page), then add the repositories that hold your deployment files to a workspace by picking them from a list — also behind a VPN. Working copies live in the workspace; a Repositories page with files, editor, changes, history, branches, pull/push and merge requests (create, comment, merge, CI status). The agent works the same way: branch → edit → commit → push → merge request, with approvals on push and merge. Repositories can be documentation for the agent — see docs/git.md.
• Domains and DNS — connect Cloudflare or ArvanCloud once under Connectors (an API token, stored in the vault), add a workspace's zones from the account, and manage their DNS records on a Domains page: status and name servers, records with TTL and the CDN (proxied) switch, add / edit / delete with every change in the activity journal. The agent's dns tool reads zones and records and changes them with the record before and after on its approval card — see .

Screenshots

Getting started

When you first open opsdeck, it asks you to create the vault (master password; there is no recovery). Then:

1. New workspace → e.g. acme.
2. Vault → Generate SSH key (or import yours); copy the public key to your servers.
3. Resources → Add resource → hosts with address, port, user, credential, and via if they sit behind a bastion or VPN. Add a WireGuard network by storing the .conf as a VPN config vault item.
4. App settings → Model providers → add an API provider (key stored in the vault), or under Local agents pick an installed CLI (Claude Code, Codex, Gemini CLI…) that you have already signed in to.
5. Agent → ask: "Check disk and memory on all prod hosts", or "Clone shop from GitLab onto test-1 and run it as a single container".

Without any model configured everything except the Agent page works.

Build from source

Requirements: Go 1.24+ (the toolchain auto-downloads 1.27) and Node 20+. For VPNs, these are optional: openvpn, openconnect (+ ocproxy), openfortivpn, wireguard-tools.

make build          # builds the web UI and bin/opsdeck
bin/opsdeck         # starts on http://127.0.0.1:7788 and opens the browser
make desktop        # the desktop app (needs the Wails CLI), see docs/desktop.md

Try it without servers

make demo
bin/opsdeck-demo -pubkey "<public key from a vault ssh-key>"

starts two local SSH servers (a bastion and an app host reachable only through it) and a scripted model endpoint (OpenAI-compatible), and prints their addresses.

Commands

opsdeck [serve] [--port 7788] [--no-open]   start the server and UI
opsdeck run -p "prompt" --ws <workspace>    run the agent headless (needs a running opsdeck)
opsdeck mcp                                 MCP server for other agents over stdio (OPSDECK_TOKEN=odk_…)
opsdeck skill install <agent>               install the opsdeck skill for claude-code, codex, gemini, cursor
opsdeck url                                 print the login link
opsdeck paths                               show where data is stored

The server only listens on 127.0.0.1. The login link carries a token (stored in the state directory); the browser keeps it as an HttpOnly cookie. Requests with a foreign Host or Origin are refused.

Data

What	Where (Linux; macOS/Windows use their app-data folders)
Vault	~/.local/share/opsdeck/vault.db
Workspaces — inventory, docs, runbooks, agent reports, memory, sessions	~/.local/share/opsdeck/workspaces/<name>/ (or any imported folder); see docs/workspace.md
Audit journal	~/.local/state/opsdeck/audit/
Settings	~/.config/opsdeck/config.yaml

OPSDECK_HOME=/some/dir puts everything under one directory.

Development

make test                                      # Go tests + TypeScript typecheck
cd web && npm run dev                          # UI dev server on :5173
bin/opsdeck --dev-origin http://localhost:5173 # backend for the dev server

The Go test suite runs real SSH servers (exec, PTY, SFTP, jump hosts), userspace WireGuard peers, a stdio MCP server and scripted models — no external infrastructure needed. The Docker and Kubernetes integration tests also run against a local dockerd and k3s cluster when one is present (OPSDECK_TEST_KUBECONFIG), the Databases tests against PostgreSQL, MySQL/MariaDB, MongoDB and Redis servers (OPSDECK_TEST_POSTGRES, OPSDECK_TEST_MYSQL, OPSDECK_TEST_MONGO, OPSDECK_TEST_REDIS = user:password@host:port/db, as CI does), and the Ansible tests against an installed ansible-core; they are skipped otherwise.

The browser tests in e2e/ drive the built UI with Playwright against a real opsdeck (tools/e2e: a fresh data folder, local SSH hosts, a scripted model): unlocking, adding a resource, search, customizing, an agent change that waits for approval, and connecting an outside agent.

cd web && npm run build && cd ../e2e
npm ci && npx playwright install chromium
npx playwright test

The README screenshots come from the demo workspace of tools/e2e -demo (see e2e/screenshots.config.ts): npx playwright test -c screenshots.config.ts there rewrites docs/assets/screenshot-*.png.

Status and known limits

• OpenVPN, OpenConnect (AnyConnect/ocserv/FortiGate/…) and openfortivpn profiles need those programs installed (ocproxy for OpenConnect userspace mode); Tailscale, NetBird and WireGuard are built in. OpenVPN and openfortivpn only run in system mode.
• Git repositories need git installed (and ssh for SSH URLs). Repository hooks don't run in opsdeck's working copies.
• Docker is driven through the docker CLI on the host over SSH (with sudo -n when the SSH user is not in the docker group); Compose needs the docker compose plugin (v2).
• PuTTY .ppk keys must be converted to OpenSSH format first.
• Kubeconfigs that use exec auth plugins run those plugins on this machine.
• Ansible needs ansible-core (and ssh) on this computer; Windows needs WSL. Hosts of the generated workspace inventory must log in with an SSH key (password logins would need sshpass).
• MCP servers from a workspace only start after you save them in Workspace settings on this machine (protects you from commands in a cloned workspace).
• The agent's access to this computer (Settings → This computer) is on by default: it can read files with consent, and every local write or command asks. Turn it off there if you only want it to work on workspace hosts.
• The agent's web access (App settings → Web access) is on by default, except in workspaces that allow only local models. Search without a key uses DuckDuckGo's HTML page, which can rate-limit heavy use; SearXNG, Brave or Tavily are steadier.
• Tested mostly on Linux. The macOS and Windows desktop apps are built and released by CI, but have seen less use.

Documents

• docs/architecture.md — framework, modules, data layout
• docs/desktop.md — the desktop app: how it works, install, build
• docs/releasing.md — versions, releases and how updates install
• docs/agents.md — use opsdeck from Claude Code, Codex, Cursor, Gemini CLI: access keys, MCP setup, the skill pack
• docs/compatibility.md — what is stable between versions, file formats, deprecation
• docs/schema.md — every resource kind and its fields (generated)
• docs/harness.md — agent loop, tools, permissions, web access, subagents, hooks, background tasks, headless runs
• docs/vault.md — vault design
• docs/workspace.md — workspace model and files
• docs/vpn.md — VPN drivers, userspace vs system mode, credentials
• docs/git.md — Git repositories, working copies, merge requests
• docs/dns.md — Domains: Cloudflare and ArvanCloud connectors, zones and records, the agent's dns tool
• docs/deployments.md — Deployments: Portainer, Argo CD and Komodo per workspace, the Deployments page, the agent's deploy tool

Contributing

Bug reports, ideas and pull requests are welcome; see CONTRIBUTING.md. Please report security problems privately as described in SECURITY.md.

License

opsdeck is released under the MIT License. The built-in skills from wshobson/agents keep their own MIT license (internal/skills/library/LICENSE-wshobson-agents).