Servidor local e API

O Jarvis Code CLI traz um servidor local embutido, somente de API. Executar jarvis server inicia um processo em primeiro plano que expõe uma API REST (/api/v1) e um fluxo de eventos por WebSocket (/api/v1/ws) para scripts e ferramentas de terceiros.

Garanta primeiro que o Jarvis Code CLI está instalado e pronto para uso — seja autenticado via /login (na TUI, ou com jarvis login), seja com um provedor configurado no config.toml. O servidor compartilha o estado de login e a configuração do CLI, então não é preciso uma credencial separada para ele.

WARNING

As APIs REST e WebSocket descritas nesta página são experimentais: a estabilidade da interface não é garantida, e endpoints, campos e tipos de evento podem mudar em qualquer release. Ao integrar, baseie-se nos documentos /openapi.json e /asyncapi.json servidos pela sua versão.

Iniciar o servidor

jarvis server
jarvis server --port 58628
jarvis server --host 127.0.0.1

Por padrão o servidor escuta em 127.0.0.1:58627 (apenas loopback). Se a porta estiver ocupada, ele tenta automaticamente a seguinte, então várias instâncias podem coexistir na mesma máquina; cada instância se registra em ~/.jarvis-code/server/instances/. O banner de inicialização imprime a URL de acesso e o token em texto puro:

text

Jarvis server ready
API:      http://127.0.0.1:58627
Token:    ...
Logs:     off  use --log-level info to enable
Stop:     Ctrl+C

O servidor roda em primeiro plano; pressione Ctrl-C para um encerramento limpo. Para a lista completa de opções, como --host e --log-level, veja a referência do comando jarvis.

Autenticação

Todo endpoint /api/* exige um bearer token (qualquer requisição que carregue essa string é considerada autorizada). O token é gerado no primeiro boot do servidor, persistido em ~/.jarvis-code/server.token (modo de arquivo 0600) e reutilizado entre reinicializações.

Escolha a forma de transporte que se encaixa no seu cliente:

REST: o cabeçalho de requisição Authorization: Bearer <token>.
WebSocket: clientes que conseguem definir cabeçalhos usam Authorization: Bearer; clientes que não conseguem (como navegadores) passam o subprotocolo (um nome de protocolo declarado durante o handshake WebSocket) jarvis-code.bearer.<token>.

Se o token vazar, execute jarvis server rotate-token: o novo token é escrito em server.token imediatamente, o antigo para de funcionar na hora e as instâncias em execução adotam o novo token sem reiniciar.

Ao escutar em um endereço não-loopback (--host), defina JARVIS_CODE_PASSWORD como credencial adicional. O bearer token persistente continua válido; a senha não o substitui. O servidor aplica limite de taxa a falhas de autenticação em binds não-loopback.

DANGER

--dangerous-bypass-auth desativa a autenticação por completo — qualquer um que alcance a porta pode controlar suas sessões, seu sistema de arquivos e seu shell. Use apenas em redes confiáveis ou atrás do seu próprio proxy autenticador. Veja a referência do comando jarvis.

Conduzir uma sessão pela API

O fluxo mínimo com curl: verificar o servidor, criar uma sessão, assinar os eventos, enviar um prompt e ler o histórico de volta. Os exemplos assumem que o servidor roda no endereço padrão e que o token está na variável de shell TOKEN.

Verifique o status do servidor:

curl -s -H "Authorization: Bearer $TOKEN" http://127.0.0.1:58627/api/v1/meta

Toda resposta JSON vem em um envelope uniforme — { "code": 0, "msg": "success", "data": ..., "request_id": "..." }. O resultado de negócio fica em code (0 significa sucesso); o status HTTP reporta apenas o resultado de transporte.

Crie uma sessão; metadata.cwd define o diretório de trabalho:

curl -s -X POST http://127.0.0.1:58627/api/v1/sessions \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"metadata": {"cwd": "/caminho/para/projeto"}}'

O data.id retornado (no formato session_...) é o id de sessão usado por todas as requisições seguintes.

Conecte-se ao WebSocket e assine os eventos da sessão. Qualquer cliente WebSocket serve; abaixo há um script Node.js sem dependências (o Node.js 22+ já traz um cliente WebSocket embutido):

// subscribe.mjs — uso: TOKEN=... node subscribe.mjs session_...
const ws = new WebSocket('ws://127.0.0.1:58627/api/v1/ws', [
  `jarvis-code.bearer.${process.env.TOKEN}`,
]);
ws.onmessage = (e) => console.log(e.data);
ws.onopen = () =>
  ws.send(
    JSON.stringify({
      type: 'subscribe',
      id: '1',
      payload: { session_ids: [process.argv[2]] },
    }),
  );

Envie um prompt:

curl -s -X POST http://127.0.0.1:58627/api/v1/sessions/<session_id>/prompts \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"content": [{"type": "text", "text": "Apresente este repositório em uma frase"}]}'

O assinante vê, nesta ordem: turn.started (o turno começa) → assistant.delta (incrementos de texto em streaming) → tool.call.started / tool.result quando há chamadas de ferramenta → turn.ended (o turno termina).

Leia o histórico de volta por REST a qualquer momento:

curl -s -H "Authorization: Bearer $TOKEN" \
  "http://127.0.0.1:58627/api/v1/sessions/<session_id>/messages?page_size=20"

Documentos de especificação ao vivo

Enquanto roda, o servidor se descreve com dois documentos de especificação, ambos exigindo o bearer token:

GET /openapi.json — um documento OpenAPI da API REST, com esquemas de requisição e resposta de cada endpoint; importe-o no Swagger UI, no Postman e em ferramentas semelhantes.
GET /asyncapi.json — um documento AsyncAPI do protocolo WebSocket, cobrindo frames de controle e tipos de evento.

Próximos passos

API do servidor — inventário completo de endpoints REST, códigos de erro, eventos WebSocket e o protocolo de transcrição
Comando jarvis — todas as opções de linha de comando do jarvis server

Servidor local e API ​

Iniciar o servidor ​

Autenticação ​

Conduzir uma sessão pela API ​