Sandbox

Sandbox é a camada de isolamento do Vectora para o acesso do agente a terminal e filesystem. Segue o design do ai-jail, do Fabio Akita — as ações do agente rodam dentro da jaula, não atrás de uma única chamada de função sandboxed — adaptado à arquitetura do Vectora: um único processo de backend de longa duração servindo vários workspaces simultâneos, em vez de um processo por invocação.

Modelo de ameaça

Sem sandbox, terminal, file_write e file_edit operam diretamente no processo do backend — o agente (ou uma injeção de prompt) pode ler ~/.ssh, exfiltrar segredos ou rodar comandos destrutivos com os mesmos privilégios do próprio backend. O Sandbox existe pra limitar esse raio de dano aos rw_paths/ro_paths declarados de um workspace, sem abrir mão completamente do acesso a arquivo e terminal (isso anularia o propósito de um agente de código autônomo).

Opt-in, por workspace

O Sandbox vem desligado por padrão. Só ativa quando o vectora.toml de um workspace tem uma seção [sandbox]:

[sandbox]
enabled = true
backend = "local"          # local (bwrap, Linux) | docker | ssh | modal
rw_paths = ["."]           # graváveis dentro da jaula
ro_paths = []               # só leitura dentro da jaula
mask = [".env", "**/*.pem", "**/.ssh/**", "**/.aws/**"]
no_gpu = true
lockdown = false            # true: fail-closed em qualquer ambiguidade de política

Sem seção [sandbox] → o workspace se comporta exatamente como antes dessa feature existir. TOML malformado ou um campo inválido, uma vez que [sandbox] está presente, falha fechado (lockdown) em vez de rodar desprotegido silenciosamente.

Como funciona: um worker por workspace

Em vez de criar um processo sandboxed novo a cada chamada de tool, o Vectora mantém um único worker jailado persistente vivo por workspace com [sandbox] habilitado — nasce na primeira ação sandboxável, é encerrado quando o workspace fica ocioso. file_write, file_edit e comandos terminal pontuais roteiam por esse worker via um protocolo JSON-lines pequeno (exec/read_file/write_file).

No backend local (só Linux), o worker roda sob bwrap (Bubblewrap) com:

• Namespacing de filesystem restrito a rw_paths/ro_paths.
• Paths mascarados (mask) nunca expostos dentro da jaula, mesmo se caírem sob um path permitido.
• Um filtro seccomp-BPF real (via libseccomp) negando uma lista fixa de syscalls perigosas (ptrace, mount, unshare, bpf, carregamento de módulo de kernel, etc.) — se libseccomp não estiver instalado no host, o worker ainda roda sob isolamento de namespace, só sem o filtro de syscall, e essa degradação é registrada em log.

Os demais backends (docker, ssh, modal) rodam o mesmo modelo de worker contra seu respectivo primitivo de isolamento; docker também nega acesso a rede sob lockdown.

Limitação conhecida: terminal interativo

A chamada pontual da tool terminal e as tools de arquivo já são sandboxed hoje. Uma sessão de terminal interativa (a aba Terminal, baseada em PTY) ainda não é roteada pelo worker jailado — iniciar um terminal interativo num workspace sandboxed retorna um erro claro em vez de cair silenciosamente pra um shell sem sandbox. Está previsto pra uma iteração futura.

Veja também

• Usando o Workbench — as abas Terminal e Arquivos na prática
• Sessões e Workspaces — como um workspace é confiado e delimitado