commandcore

CommandCore

Self-hosted remote computer control for AI and MCP clients.

CommandCore connects AI clients to one or more computers through a vendor-neutral MCP control plane. Devices make outbound connections to the server, retain their own cryptographic identity, and enforce local permission ceilings.

CommandCore is free software licensed under GNU AGPL-3.0-or-later.

Project status: 0.9 release-candidate family. Linux is the primary supported platform. Windows support is a preview. Interactive desktop control is experimental and is not yet part of the stable support promise.

Why CommandCore?

Most computer-control MCP tools focus on one client talking to one machine. CommandCore is designed as a control plane:

ChatGPT -+
Claude --+
Gemini --+
Codex ---+-- MCP + OAuth --> CommandCore -- outbound WSS --> devices
IDE/CLI -+                       |
Other ---+                       +-- identity and grants
                                +-- policy and audit
                                +-- device selection
                                +-- signed agent lifecycle

A single MCP endpoint can expose every device the authenticated account is allowed to use. Adding a device does not require adding another MCP server to each AI client.

Core properties

• Self-hosted control plane - server, protocol, agent, and deployment tooling are in this repository.
• Vendor-neutral MCP - the control plane does not depend on one AI provider.
• Multi-device by design - enumerate, select, and operate authorized devices.
• Outbound-only device transport - enrolled devices do not need inbound command ports.
• Cryptographic device identity - each agent keeps its Ed25519 private key locally.
• Layered authorization - OAuth scope, account-to-device grant, server profile, and device-local ceiling all restrict effective authority.
• Privilege separation on Linux - optional FULL_CONTROL uses a separate local privileged helper rather than making the network-facing agent root.
• Auditable operations - remote work is associated with identity, device, request, and execution metadata.
• Managed long-running jobs - process handles and bounded output survive transport/server reconnects in the native Linux agent.
• Signed agent releases - integrity verification, versioned installation, health validation, and rollback are first-class lifecycle concerns.

Security model

CommandCore intentionally does not treat enrollment as authorization.

effective authority =
    OAuth scope
    AND account -> device grant
    AND server permission profile
    AND device-local permission ceiling

Profiles:

Profile	Meaning
READ_ONLY	Inspect permitted state and files
STANDARD	Normal operating-system authority of the agent user
FULL_CONTROL	Explicit local privileged-helper opt-in

STANDARD shell access is powerful: it has the same authority as the operating system account running the agent. Run the agent as a dedicated unprivileged user when stronger host separation is required.

Read SECURITY.md, Security model, and Threat model before exposing a deployment to untrusted clients.

Capabilities

The current Linux implementation covers:

• filesystem list/stat/read/write/patch/search/copy/move/delete;
• shell execution;
• managed processes, status, output, and cancellation;
• system information and metrics;
• upload/download transfer primitives;
• Git operations;
• device enrollment, revocation, reconnect, and key rotation;
• OAuth-protected MCP access and explicit device grants;
• signed agent installation/update/rollback;
• fleet/canary rollout primitives;
• optional privilege-separated Linux FULL_CONTROL.

Interactive screen, mouse, keyboard, clipboard, browser automation, and some platform-specific administration remain experimental or incomplete. The project does not claim support from compilation alone; see the platform matrix.

Install with an AI agent

CommandCore includes a root-level AGENTS.md with repository-specific instructions for coding and operations agents, plus a human-readable agent-assisted installation guide.

A capable agent with access to the target server can inspect the machine, prepare the deployment, start CommandCore, configure the pieces it has authority to configure, and verify the result. Account-bound steps such as DNS ownership, OAuth provider login, MFA, or permission decisions remain with the operator.

A portable starting prompt is:

Clone https://github.com/bazobehram/commandcore.git and read AGENTS.md before
making any changes.

Install a self-hosted CommandCore server on this machine and make it usable for
remote MCP clients. Preserve the documented security model: keep the internal
application port private, use HTTPS/WSS for remote access, configure OAuth/OIDC
instead of leaving public bootstrap enabled, and do not enable FULL_CONTROL
unless I explicitly request it.

Inspect the machine first. Ask me only for account-bound information you cannot
safely infer. Verify /healthz and the MCP path, perform a read-only acceptance
test when a device is enrolled, and finish with the exact public URL, MCP URL,
Agent URL, OAuth status, permission ceiling, tests performed, rollback path, and
remaining manual steps.

AGENTS.md is a repository convention used by many coding agents, not a part of the MCP protocol itself. Agents that do not load it automatically should be explicitly told to read it first.

Quick start

Choose two roles: the server hosts the panel, identity/grants, and MCP endpoint; an agent runs on each computer you want to manage. They can share one Linux machine. Running the server alone does not enroll or give control of that machine.

The source checkout is suitable for technical Linux operators. Remote setup also requires HTTPS/WSS and an OAuth/OIDC provider. The signed agent installer needs a separately published release feed; it is not enabled by the default Compose file. See the installation readiness review before choosing a platform or promising an unattended installation.

1. Run CommandCore

Requirements: Docker with Compose.

git clone https://github.com/bazobehram/commandcore.git
cd commandcore
cp .env.example .env

# Generate two different secrets and place them in .env:
./scripts/generate-secret.sh   # COMMANDCORE_API_TOKEN
./scripts/generate-secret.sh   # COMMANDCORE_PANEL_SESSION_SECRET

# Set the deployment URLs in .env, then:
docker compose up -d --build
docker compose ps
curl -fsS http://127.0.0.1:8787/healthz

The public example binds the application port to 127.0.0.1. Public bootstrap and recovery are disabled by default. For a loopback-only first-time onboarding window, an operator may deliberately enable bootstrap, configure OAuth/OIDC, test it, and disable bootstrap again before normal remote operation.

For internet-facing deployments, use HTTPS/WSS behind a reverse proxy and configure an external OAuth/OIDC provider. See Self-hosting, Deployment, and OAuth/MCP.

2. Install an agent

A deployment can publish its signed Linux installer at its own CommandCore URL:

curl -fsSL https://commandcore.example.com/install/linux | sh -s -- --server https://commandcore.example.com

The installer verifies the signed release manifest and artifact, creates a versioned user installation, configures a systemd user service, and opens the device-enrollment flow. Replace commandcore.example.com with your deployment.

First confirm the operator has published the signed feed and pinned installer. A fresh default server returns 404 for /install/linux. Operators should follow release-feed setup; technical evaluators can use the source agent workflow.

See Installation for upgrade, rollback, uninstall, and advanced installation details.

3. Connect an MCP client

Use the deployment MCP endpoint:

https://commandcore.example.com/mcp

Then authenticate with the configured OAuth/OIDC provider and grant only the devices and scopes the client needs.

Client guides:

• ChatGPT
• Claude
• Gemini
• Codex
• Generic MCP clients

Client product capabilities change independently of CommandCore. Each guide distinguishes protocol support from live acceptance evidence.

Platform status

Platform	Status	Notes
Linux x86_64	Supported candidate	Python reference + native Rust agent
Linux ARM64	Supported candidate	Native Rust agent
Windows	Preview	Core enrollment/runtime work exists; release gates remain
macOS	Planned	No supported agent release yet
Interactive desktop	Experimental	Not part of stable support promise

CommandCore and Desktop Commander

CommandCore is not a fork of Desktop Commander. The projects solve overlapping but different problems: Desktop Commander has a mature local computer-tool surface, while CommandCore focuses on a self-hosted, multi-device remote control plane with explicit identity, grants, policy, and agent lifecycle.

The comparison is intentionally factual rather than adversarial. See CommandCore and Desktop Commander.

Documentation

Start with the documentation index. Important references:

• Architecture
• MCP contract
• Device protocol
• Permissions
• Agent architecture
• Observability
• Operator guide
• Development
• Release process
• Roadmap

Contributing

Contributions are welcome. Before opening a pull request, read CONTRIBUTING.md.

The project uses review-first development:

• changes arrive through pull requests;
• CI must pass;
• security-boundary changes require explicit security review;
• protocol changes require compatibility notes and tests;
• claims about platform support require real acceptance evidence;
• commits must carry a Signed-off-by line under the Developer Certificate of Origin policy described in CONTRIBUTING.md.

Sensitive vulnerabilities must not be reported in public issues. Follow SECURITY.md.

License

CommandCore is licensed under the GNU Affero General Public License, version 3 or later.

If you modify CommandCore and make the modified program available to users over a network, review the AGPL source-availability requirements that apply to that use. Third-party dependencies retain their own licenses; see THIRD_PARTY_NOTICES.md and dependency licensing.