O que é o OKAMI OS? What is OKAMI OS?

01quick start

Rode primeiro em modo mock. Conecte depois. Run mock mode first. Connect later.

O projeto não exige runtime real para abrir a interface. Se nenhuma API estiver configurada, o hook useMissionControl usa src/data/mockMissionControl.js. Isso permite testar layout, navegação, Pixel Office, docs e gráficos antes de plugar dados reais. The project does not require a real runtime to open the UI. If no API is configured, useMissionControl uses src/data/mockMissionControl.js. This lets you test layout, navigation, Pixel Office, docs and charts before plugging in real data.

git clone https://github.com/OkamiOps/Okami-Monitor.git okami-os
cd okami-os
npm install
cp .env.example .env.local
npm run dev:all

02environment

Variáveis que mudam o modo de execução. Variables that change runtime behavior.

O arquivo .env.example define o contrato mínimo. Em desenvolvimento, vite.config.js encaminha /api para http://127.0.0.1:3001. Em produção, same-origin assume que existe uma função/proxy atendendo o caminho /api. The .env.example file defines the minimum contract. In development, vite.config.js proxies /api to http://127.0.0.1:3001. In production, same-origin assumes a function/proxy is serving the /api path.

03project map

Como o repositório está organizado. How the repository is organized.

04modules

As 14 telas visíveis do cockpit. The 14 visible cockpit screens.

A navegação é definida em navGroups dentro de src/App.jsx. Cada view recebe o mesmo estado base de useMissionControl e decide quais blocos renderizar. Navigation is defined in navGroups inside src/App.jsx. Each view receives the same base state from useMissionControl and decides which blocks to render.

05agents

A aba Agentes é o centro de conexão do painel. The Agents tab is the panel connection center.

No código atual, a view visível Agentes mantém o hash #config por compatibilidade, mas substitui as antigas telas separadas de Config, Agentes e Hermes. Ela prepara o acesso ao painel, conecta o servidor onde os agentes rodam e registra agentes externos sem exigir que o usuário edite secrets manualmente. In the current code, the visible Agents view keeps the #config hash for compatibility, but replaces the older separate Config, Agents and Hermes screens. It prepares panel access, connects the server where agents run and registers external agents without making users edit secrets manually.

{
  "runtime": {
    "id": "opencode",
    "name": "OpenCode",
    "family": "coding-cli",
    "command": "opencode status",
    "home": "~/.agents/workspaces/opencode",
    "workspacePath": "~/.agents/workspaces/opencode",
    "configPath": "~/.agents/registry.json",
    "recommendedScopes": ["read", "write"]
  }
}

06frontend

Fluxo de dados no frontend. Frontend data flow.

07state model

Contrato de estado que alimenta a UI. State contract that feeds the UI.

O shape abaixo é o centro do projeto. O painel não depende de uma infraestrutura específica: qualquer backend pode preencher esse contrato e a UI passa a mostrar seus agentes. The shape below is the center of the project. The panel does not depend on a specific infrastructure: any backend can fill this contract and the UI will show your agents.

{
  "status": { "label": "Runtime online", "healthy": true, "updatedAt": "..." },
  "metrics": [{ "label": "tokens hoje", "value": "304.3k", "delta": "+18%" }],
  "tokenSeries": { "input": [1200, 1500], "output": [320, 410] },
  "overview": { "serviceHealth": [], "queue": [], "incidents": [] },
  "models": [{ "name": "gpt-5.4", "share": 10 }],
  "activity": [{ "actor": "agent", "message": "...", "status": "OK" }],
  "subscriptions": [],
  "agents": [],
  "agentRuntimes": [],
  "liveEvents": [],
  "kanban": { "Backlog": [], "Todo": [], "Done": [] },
  "apiKeys": [],
  "apps": [],
  "docs": [],
  "hermes": {},
  "cliTools": []
}

08api

Rotas reais do backend Express. Real Express backend routes.

O backend roda em server/index.js. As rotas públicas cobrem health e status de auth; as demais exigem token de proxy, token estático, loopback confiável em dev ou uma Okami API Key com escopo suficiente. The backend runs in server/index.js. Public routes cover health and auth status; the others require a proxy token, static token, trusted loopback in dev or an Okami API Key with enough scope.

Escopos de API KeyAPI Key scopes

09sse

Como o stream ao vivo funciona. How the live stream works.

event: state
data: {"status":{"healthy":true},"agents":[]}

event: heartbeat
data: {"t":1782130000000}

event: error
data: {"message":"SSH timeout"}

10registries

Store local, registries e secrets. Local store, registries and secrets.

O backend usa server/.data para persistir configuração local. Essa pasta deve permanecer fora do Git. Ela permite salvar preferências, apps, docs, APIs e credenciais sem colocar segredos no repositório. The backend uses server/.data to persist local configuration. This folder must stay out of Git. It lets you save preferences, apps, docs, APIs and credentials without putting secrets in the repository.

11runtime bridge

Conecte qualquer runtime compatível ao painel. Connect any compatible runtime to the panel.

O backend ainda usa o prefixo /api/hermes/* por compatibilidade histórica, mas a função é genérica: coletar dados do ambiente do usuário, normalizar no contrato de estado e manter credenciais isoladas no backend. The backend still uses the /api/hermes/* prefix for historical compatibility, but the function is generic: collect data from the user's environment, normalize it into the state contract and keep credentials isolated in the backend.

O que o collector tenta lerWhat the collector tries to read

12pixel office

Pixel Office

O Pixel Office fica em src/PixelOfficeCanvas.jsx. Ele usa Phaser 4 em modo Canvas, carrega sprites de agentes, tiles/objetos do escritório, desenha zonas, mesas, paredes, mini Kanban e movimenta pessoas por rotas ortogonais. Pixel Office lives in src/PixelOfficeCanvas.jsx. It uses Phaser 4 in Canvas mode, loads agent sprites, office tiles/objects, draws zones, desks, walls, mini Kanban and moves people through orthogonal routes.

13design system

Tokens visuais e convenções de UI. Visual tokens and UI conventions.

14deploy

Build, preview e proxy de produção. Build, preview and production proxy.

npm run build
npm run preview

O repositório inclui functions/api/[[path]].js para Cloudflare Pages. A função copia headers seguros, remove hop-by-hop headers, injeta x-okami-proxy-token e encaminha chamadas para OKAMI_BACKEND_URL. Se o proxy não estiver configurado, retorna 503. The repository includes functions/api/[[path]].js for Cloudflare Pages. The function copies safe headers, removes hop-by-hop headers, injects x-okami-proxy-token and forwards calls to OKAMI_BACKEND_URL. If the proxy is not configured, it returns 503.

15security

Cuidados de segurança ao conectar dados reais. Security notes for real data integrations.

• Não versione server/.data, .env.local, private keys, senhas ou dumps de sessão.Do not version server/.data, .env.local, private keys, passwords or session dumps.
• Trate Okami API Keys como credenciais reais: o token completo aparece uma única vez e o backend persiste somente hash, prefixo e escopos.Treat Okami API Keys as real credentials: the full token is shown once and the backend stores only hash, prefix and scopes.
• Prefira usuário SSH com permissões mínimas para leitura e comandos específicos.Prefer an SSH user with minimal permissions for reading and specific commands.
• Revise o allowlist de /api/hermes/command antes de liberar para outras pessoas.Review the /api/hermes/command allowlist before exposing it to other people.
• Mantenha OKAMI_TRUST_LOCAL_DEV=0 se o ambiente local for compartilhado ou exposto por túnel.Keep OKAMI_TRUST_LOCAL_DEV=0 if the local environment is shared or exposed through a tunnel.
• Mantenha o backend atrás de token, VPN, Cloudflare Access ou rede privada quando usar dados reais.Keep the backend behind a token, VPN, Cloudflare Access or private network when using real data.
• Redija logs e documentos antes de renderizar conteúdo em ambientes compartilhados.Redact logs and documents before rendering content in shared environments.

16troubleshooting

Problemas comuns. Common issues.

17contribute

Como contribuir sem quebrar o painel. How to contribute without breaking the panel.