Arquivos por SFTP

Deixe um agente listar, ler, gravar e mover arquivos no seu servidor enquanto o Sallyport guarda a chave privada.

Nesta página

Configuração
Escolha quais operações esperam por você
Use a partir de um agente
Arquivos grandes por HTTP
Leia o resultado

Cada host SSH que você conecta também é um servidor de arquivos para os seus agentes. O Sallyport entra com a sua chave, faz a operação com o arquivo e devolve o resultado. O agente nunca vê a chave, e cada operação fica no registro.

Configuração

Não há mais nada a adicionar. Conecte o host SSH uma vez: a mesma conexão, a mesma chave e a mesma chave de host servem os comandos e os arquivos. O servidor precisa do subsistema SFTP, que o OpenSSH liga por padrão.

Escolha quais operações esperam por você

Operação	Classe
`list`, `stat`, `read`	Leitura. Ler uma chave privada, `.env`, um arquivo de senhas ou um caminho com `..` conta como escrita.
`write`, `mkdir`, `rename`	Escrita
`overwrite`, `delete`, `rmdir`	Destrutiva

Por padrão, operações com arquivos rodam sem perguntar. Ajuste cada classe na página do agente em Agentes, como para comandos. O cartão de aprovação mostra o host, a operação e o caminho e, numa gravação, o texto que vai para o arquivo. Bytes que não são texto aparecem com o tamanho e o SHA-256.

Use a partir de um agente

list_access nomeia as duas ferramentas de arquivos do host. _sftp_read aceita só leituras, então um cliente pode permiti-la uma vez. _sftp_write aceita todas as operações.

Argumento	Significado
`op`	`list`, `stat`, `read`, `write`, `overwrite`, `mkdir`, `rename`, `delete` ou `rmdir`. Obrigatório.
`path`	O arquivo ou diretório: caminho absoluto ou relativo ao diretório de login. Obrigatório.
`to`	`rename`: o caminho novo. Renomear nunca substitui um arquivo que já existe.
`offset`, `length`	`read`: a parte do arquivo a ler.
`content`, `content_base64`	`write`, `overwrite`: o arquivo como texto ou os bytes em base64. `write` cria um arquivo novo e nunca substitui um que já existe; `overwrite` substitui o arquivo inteiro, com um único cartão para aprovar.
`intent`	Uma frase sobre o motivo, mostrada a quem aprova.
`call_id`	Continua uma chamada que espera aprovação.
`max_inline_bytes`	Quanto vem na resposta. 24 KiB por padrão; `fetch_body` lê o resto.

Argumentos de uma chamada a _sftp_write

{
  "op": "write",
  "path": "upload/ledger.csv",
  "content": "id,amount\n1,100.50\n",
  "intent": "Send the September ledger to the bank"
}

Arquivos grandes por HTTP

Um arquivo grande demais para uma chamada MCP passa pelo proxy HTTP com o token do agente. O caminho depois do id da conexão é o caminho absoluto do arquivo, e o método é a operação. Um download flui conforme o servidor envia, e um upload aceita até 32 MiB.

Requisição	Operação
`GET /p/{id}/srv/report.csv`	`read`. Adicione `?offset=` e `&length=` para uma parte.
`GET /p/{id}/srv/reports/`	`list`: uma barra no fim.
`HEAD /p/{id}/srv/report.csv`	`stat`
`PUT /p/{id}/upload/ledger.csv`	`write`; com `?op=overwrite`, `overwrite`. O corpo é o arquivo.
`POST /p/{id}/upload/2026?op=mkdir`	`mkdir`
`POST /p/{id}/inbox/a.xml?op=rename&to=/archive/a.xml`	`rename`
`DELETE /p/{id}/inbox/a.xml`	`delete`. Com uma barra no fim, `rmdir`.

Shell · envie um arquivo e depois baixe-o

export SP_TOKEN='sp_live_…'
BINDING='<ssh-connection-id>'

curl --fail-with-body -X PUT -H "Authorization: Bearer $SP_TOKEN" \
  -H 'X-Sallyport-Intent: Send the September ledger to the bank' \
  --data-binary @ledger.csv \
  "https://mcp.sallyport.cloud/p/$BINDING/upload/ledger.csv"

curl --fail-with-body -H "Authorization: Bearer $SP_TOKEN" \
  -o ledger-copy.csv \
  "https://mcp.sallyport.cloud/p/$BINDING/upload/ledger.csv"

Leia o resultado

Uma leitura responde com content quando o arquivo é texto e content_base64 quando não é, além de file_size.
Uma listagem responde com entries: nome, tipo, tamanho, permissões e hora da alteração. stat responde com uma entry.
Uma recusa do servidor é a resposta, e nada mais foi feito: no_such_file, permission_denied, already_exists, is_a_directory ou failure, com a mensagem do servidor. Em /p/ ela chega como 404, 403 ou 409.
Abra a chamada em Atividade para ver Resultado da operação com arquivo: o destino, o caminho e os bytes movidos. O registro guarda a operação e o caminho, nunca o conteúdo do arquivo.