Projects is the control plane — the human surface where you launch, watch, approve and replay missions. Sidekick is its CLI and deployment arm, driving Terraform and Ansible underneath. The one idea that makes this a get-started guide and not a dashboard tour: a deployment is itself a governed mission — planned, gated on a human approval, backed by evidence, and unwound by a saga if it fails. You approve from the cockpit; the work runs on the infra.
The combo ships as the deploy/sidekick-devops bundle in the public agentic-os repo — clone it first (steps below). "One-click" here honestly means one command — a single docker compose up on a host, or one helm install in a cluster. Both stand up the runtime, the Projects Control Plane, the infra operator (deploy · provision · configure · verify · drift · rollback, each a gated capability), the deployment skills, and a wired Prometheus + Grafana + Loki stack.
Running it on your own models? Install the stack with the steps here, then see Run it on your own models — point every agent at a model on your own hardware (Ollama · local vLLM · NVIDIA PAIR), and share one database and one model across several installs.
Just want the Projects workspace + Sidekick — not the full monitoring combo? The Projects UI and its API ship as one service in the same agentic-os package (the UI is served at the same origin as the API — no CORS, one port).
Prerequisites for the pip path — Python 3.11+ and Git, both on PATH: the package installs from source and pulls a couple of Git-based dependencies. A stock Windows box has neither, and a fresh macOS ships an older system Python — install them first, then use a virtualenv so it stays self-contained:
# Windows (PowerShell): winget install -e --id Python.Python.3.12 winget install -e --id Git.Git # macOS (Homebrew): brew install python@3.12 git # Debian / Ubuntu: sudo apt install -y python3 python3-venv git
# the whole Projects experience — UI + API — on one origin python -m venv .venv . .venv/bin/activate # Windows: .venv\Scripts\Activate.ps1 pip install 'agentic-os[projects] @ git+https://github.com/redevops-io/agentic-os' agentic-os-projects # → http://127.0.0.1:8787
Or containerised — only Docker is required (no Python or Git); clone the repo, then:
git clone https://github.com/redevops-io/agentic-os && cd agentic-os
docker build -f Dockerfile.projects -t redevops-projects .
docker run -p 8787:8787 redevops-projects # → http://localhost:8787
Open the URL and you're in Projects — connect apps, add data sources, and ask Sidekick to run a governed Mission. The [projects] extra pulls the connector plugin so Connect / Add-source work against real providers. This is the fastest path to the new UI; the combo above adds the infra operator and the Prometheus + Grafana + Loki stack.
Install only the apps you want. The base install is already minimal — the connectors are stdlib-only — so per-app extras are about selecting which apps a deployment offers, not shrinking a download. Install just the ones you need, and they compose:
# one app — Google Workspace (Gmail, Drive, Calendar) pip install 'agentic-os[google] @ git+https://github.com/redevops-io/agentic-os' # compose several — or the office convenience extra (Google + Microsoft) pip install 'agentic-os[slack,stripe] @ git+https://github.com/redevops-io/agentic-os' pip install 'agentic-os[office] @ git+https://github.com/redevops-io/agentic-os'
The productivity plane also does local document work with no extra: LibreOffice conversions (via a system soffice) and raw file formats — CSV, Markdown, XLSX, DOCX — using only the standard library, so those documents never leave your machine.
…and pick which apps the UI offers at runtime with PROJECTS_APPS — a comma-separated list of provider ids. Projects then shows and lets you connect only those apps; unset (the default) offers all of them:
# the Apps surface and Connect offer only these three
PROJECTS_APPS=google,slack,stripe agentic-os-projects
Uninstall — identical on Windows, macOS and Linux:
# pip path — remove the package + the agentic-os-projects command: pip uninstall -y agentic-os # …or, cleanest, just delete the virtualenv (removes the package AND its deps): # rm -rf .venv (Windows: Remove-Item -Recurse -Force .venv) # Docker path — stop the container and drop the image: docker rm -f $(docker ps -aq --filter ancestor=redevops-projects) docker rmi redevops-projects
You need Docker (with the Compose plugin) and a read-only kubeconfig for the cluster you want to inspect.
# 1 · clone the public bundle git clone https://github.com/redevops-io/agentic-os cd agentic-os/deploy/sidekick-devops # 2 · configure cp .env.example .env # edit .env — the two you must set: # MODEL_ENDPOINT = your LLM endpoint, e.g. http://my-llm:8000/v1 # KUBECONFIG_HOST = path to a READ-ONLY kubeconfig (mounted :ro) docker compose up # builds Sidekick; starts Prometheus + Grafana + Loki + Promtail
Then open the cockpit:
Cockpit http://localhost:8000/cockpit # launch · watch · approve · EXPLAIN Missions API http://localhost:8000/missions Observability http://localhost:8000/observability Grafana http://localhost:3000 # Prometheus + Loki pre-wired
Identical to Linux — Docker Desktop for Mac provides the Compose plugin. Point KUBECONFIG_HOST at a read-only kubeconfig.
git clone https://github.com/redevops-io/agentic-os
cd agentic-os/deploy/sidekick-devops
cp .env.example .env
# set MODEL_ENDPOINT + KUBECONFIG_HOST in .env
docker compose up
Open http://localhost:8000/cockpit (and Grafana on http://localhost:3000). Apple-silicon and Intel are both fine; the images are the same the Linux host runs.
Use Docker Desktop with the WSL2 backend. Run the bundle from inside your WSL2 distro (e.g. Ubuntu) so the compose file, .env and the mounted kubeconfig live on the Linux filesystem — the steps are then identical.
# inside WSL2 git clone https://github.com/redevops-io/agentic-os cd agentic-os/deploy/sidekick-devops cp .env.example .env # set MODEL_ENDPOINT + KUBECONFIG_HOST in .env docker compose up
Open http://localhost:8000/cockpit in your Windows browser — Docker Desktop forwards the port out of WSL2 automatically.
Instead of a host, run Sidekick inside Kubernetes. The chart bakes in a read-only ServiceAccount (pods + metrics get/list only) — there is no kubeconfig to mount.
git clone https://github.com/redevops-io/agentic-os cd agentic-os/deploy/sidekick-devops helm install sidekick ./helm --set model.endpoint=http://my-llm:8000/v1
Environment you'll set. MODEL_ENDPOINT (the LLM) and KUBECONFIG_HOST (read-only kubeconfig) are the two required for compose. Optional: ALERT_WEBHOOK_URL + COCKPIT_URL (turn on stakeholder sign-off alerts — see §4), and PROMETHEUS_URL / LOKI_URL / GRAFANA_URL / INSPECT_NAMESPACE to point at your own signals. Pin note: the image pins fastapi==0.115.6 — a mismatched Starlette breaks FastAPI's include_router, so don't float it.
There is no iOS install target. The Sidekick runtime runs on a Linux, macOS or Windows host, or in a cluster — not on a phone. But because the cockpit is just a web surface, you operate and approve from any device's browser, iOS Safari included: open the cockpit URL, read the approval packet, and sign off. The runtime stays on the host or cluster; your device is only the window onto it.
:ro, cluster reads are get/list only, and every side-effecting capability (infra.provision, infra.destroy_delta, …) is gated — the mission parks on a human approval in the cockpit inbox before anything mutates.Want the runtime itself — not the Sidekick combo? The reference-system/redevops-runtime Helm chart deploys the public Python runtime (the Projects Control Plane: dashboard, /health, runnable missions, approvals, permissions) with two things that are the whole point: the deployment is itself a mission — a post-install gate runs acceptance checks and fails the release if they don't pass — and execution inside is deterministic (deny-by-default grants, an event-sourced replayable ledger, verification on). The runtime image is public: ghcr.io/redevops-io/redevops-runtime.
git clone https://github.com/redevops-io/agentic-os # self-contained demo (bundled retrieval, no external model): helm install rr ./agentic-os/deploy/reference-system/redevops-runtime \ --set retriever.backend=inmemory # or point it at your OpenAI-compatible model + a managed pgvector DSN: helm install rr ./agentic-os/deploy/reference-system/redevops-runtime \ --set model.endpoint=http://my-llm:8000/v1 \ --set retriever.pgvector.dsn=postgres://user:pass@host:5432/redevops_rag
Runs on any Kubernetes (ROCm/Instinct-ready via model.server.enabled=true). This is the public, open-core runtime; the Go and Kotlin runtime editions ship as separate private charts — the commercial layer, available on request. See the architecture overview.
Chart 0.3.0 can wire the intrinsic-security, telemetry and credential-brokerage plugins. They are off by default — the open runtime is unchanged when disabled — and require the enterprise runtime image that bundles the private enforcement (the open image cannot import it). That image is private: pulling it needs a registry account ReDevOps has granted access to, supplied to the cluster as an image pull secret (--set imagePullSecrets[0].name=<your-secret>, or your own mirror registry). The canonical contracts stay open in runtime-contracts; these values only enable their production enforcement:
helm install rr ./agentic-os/deploy/reference-system/redevops-runtime \
# intrinsic security: sandbox + boundary correlation → containment
--set security.enabled=true \
--set security.image.repository=ghcr.io/redevops-io/redevops-runtime-enterprise \
# authority-scoped credential broker — secrets never enter a plan/context/telemetry
--set security.credentialBroker.enabled=true \
--set security.credentialBroker.backend=vault \
--set security.credentialBroker.assurance=production \
--set security.credentialBroker.vault.addr=https://vault.vault:8200 \
--set security.credentialBroker.vault.auth.method=kubernetes \
# Mission-rooted OpenTelemetry export (native record is the source of truth)
--set telemetry.otel.enabled=true \
--set telemetry.otel.endpoint=http://otel-collector:4317
The broker backend is pluggable — local (dev env/file providers, the open floor), vault, or openbao; a capability that declares it needs a production broker fails closed if only a development one is wired. See the enterprise plugins and the benchmarks.
See the v0.3.0 planes running: permissions (data-access grants) · intrinsic security (decisions · telemetry · containment) · evidence explorer (query a run's saved canonical evidence) · compliance (control posture + framework crosswalk — can ReDevOps govern itself?) · geospatial (zoning intelligence). Each runs the real runtime, not a mock.
You don't wire a pipeline. You tell Sidekick what to ship and where — the destination repo and the target are just parameters in the prompt. Sidekick picks the matching per-provider runbook (deployment-aws, deployment-gcp, deployment-azure, deployment-digitalocean, deployment-proxmox), and runs the deploy_app mission. Some concrete prompts:
Deploy the app in github.com/acme/api to AWS EKS (staging). Use the deployment-aws runbook; stop at the approval gate.
Sidekick runs deployment-aws → infra.plan produces the terraform plan diff as evidence (infra_planned) → the mission parks on the approval gate in your cockpit inbox. Nothing has been applied. You approve → infra.provision (EKS + ECR + ALB + Route 53) → infra.configure (Ansible pulls the image, rolls out) → infra.verify (/health + /capabilities + one smoke request).
Provision a Proxmox k3s node and deploy github.com/acme/dashboard to it.
Sidekick runs deployment-proxmox → infra.plan clones a VM template (terraform plan) as evidence → approval gate → on sign-off, infra.provision creates the VM/LXC, infra.configure installs k3s, pulls from the local registry, and stands up a cloudflared tunnel (no inbound ports opened) → infra.verify probes the service.
Deploy github.com/acme/worker to DigitalOcean DOKS, region nyc3.
Sidekick runs deployment-digitalocean → infra.plan (terraform plan -var region=nyc3) → approval gate → infra.provision (DOKS + DOCR + managed DB + LB) → infra.configure (pull from DOCR, roll out) → infra.verify.
Deploy github.com/acme/billing to GCP GKE, project acme-prod, region europe-west1.
Sidekick runs deployment-gcp with the same shape — plan → approval gate → provision → configure → verify. Swap the runbook for the target; the mission graph is identical.
Every one of these is the same governed mission with a different arm. The graph reads: infra.plan → approval gate → infra.provision → infra.configure → infra.verify. An image and dependency vulnerability scan (planned, not implemented today) is not part of this flow, and no deploy is gated on CVE results.
infra.plan → [ APPROVAL GATE ] → infra.provision → infra.configure → infra.verify
terraform plan human sign-off terraform apply ansible-playbook /health + smoke
(the diff in the cockpit undo=rollback_ undo=destroy_delta
is evidence) inbox release
│ reject, or any step fails
▼
saga unwinds: infra.rollback_release → infra.destroy_delta
(redeploy prior release, then tear down the just-applied delta)deployment-stack-selection first to recommend where.infra.plan is read-only — it runs terraform plan and attaches the diff to the mission as infra_planned. Nothing is applied yet.infra.provision is the highest-consequence capability in the fleet — approval_required. It surfaces in the cockpit as an approval packet carrying the plan diff and blast radius. Never auto-approved.infra.rollback_release redeploys the prior release, then infra.destroy_delta tears down the just-applied Terraform delta. You never leave a half-applied stack.github.com/acme/api and AWS EKS to any repo and any of the five providers — the mission, the gate, the evidence and the saga are the same every time.Deployment is where most tools stop. Here the same container keeps running as a continuous monitoring agent — the loop lives on the infra, so your laptop can be off.
ALERT_WEBHOOK_URL (Slack-compatible or any JSON endpoint) and that gate becomes a stakeholder sign-off alert: a webhook message with a cockpit deep-link (COCKPIT_URL) — the fast path from issue detected to a human approves the fix. Alerting stays off until the webhook is set; the agent mutates nothing without sign-off.Every mission — deploy or response — is inspectable the same way, because the store is event-sourced:
Grafana, Prometheus and Loki are wired out of the box (Grafana on :3000, datasources pre-provisioned) for the raw metrics and logs behind the missions.
The loop runs on the infra, not your machine. Once the combo is up on a host or in a cluster, you can close the laptop. The monitor keeps watching; when it needs you, it reaches out via the webhook with a deep-link, and you approve from whatever device is nearest — including iOS Safari.
The combo ships a permissions plane at /permissions — configure it at deploy time so every app and agent sees only the data it should. A grant reads <subject> may <actions> on <resource>, sliced by row-scope and column-mask, and you preview it live (full vs. permissioned) before trusting it. Deny is the default — least privilege out of the box.
app, a role (e.g. finance), or a user.database / table / corpus / tool (a grant on crm covers crm.customers).all, own (rows where a column == the user), or in (e.g. region ∈ [us]); column-mask nulls sensitive values server-side.Configure it by telling Sidekick what you want — it follows the deployment-permissions runbook — or edit at /permissions directly. A concrete prompt:
Grant the support app read access to crm.customers, but only US rows and mask the email column. Then preview what support can see.
Sidekick follows deployment-permissions → adds the grant (row_scope: in, region=[us], masked: [email]) → runs preview: of 10 rows, support sees 4, with email masked. Grants persist encrypted, fail-closed to the mounted volume; the client apps enforce the same store on every tool call.
For production, provision PERMISSIONS_KEY (at-rest encryption) from your secrets manager and set PERMISSIONS_ADMIN_KEY so grant edits are authenticated; on localhost you can leave both unset.
An agentic stack shouldn't force every user to begin by creating a cloud-model account and pasting an API key. ReDevOps is provider-agnostic: it resolves whatever inference path you already have, and can use local inference with NVIDIA PAIR to route work across the machines you own — cloud fallback happens only when Mission policy allows it.
On first run the Runtime walks a ladder from "use what you have" to "guided setup", so there is no API key needed to start:
| Your situation | What ReDevOps does |
|---|---|
| Already have provider credentials | Use them — your existing cloud or self-hosted model, unchanged. |
| PAIR / local AI available | Use it — local inference with NVIDIA PAIR across your devices (PC · GPU · Mac). |
| Capable machine, no local AI yet | Offer a governed local-AI setup — provisioned as a mission, not a manual slog. |
| Neither | Guided cloud setup — a short, walked path to a working provider. |
Cloud only when policy allows. Where a request runs — a local device via PAIR, or a cloud provider — is a Mission policy decision, gated and recorded like any other capability. Keep sensitive inference on your own hardware and let policy decide when it may leave.
Bring your own model → Once the stack is up, Run it on your own models takes the model layer end to end: point REDEVOPS_LLM_BASE_URL at Ollama, a local vLLM or another machine via NVIDIA PAIR, and run several instances off one shared database and model. No cloud dependency.
Questions, or stuck on a step? Ask in #agentic-apps on the ReDevOps Slack, or email info@redevops.io — the team and community help with deploys, connectors, sources and governance there.