Português
Menu da documentação

Docs do Agent Sandboxes · Tarefas

SSH em um sandbox: shell, scp, SFTP e túneis

Atualizado em · 5 min de leitura

Todo sandbox aceita ssh, scp, sftp e ssh -L puros: ssh <sandbox id>@<server> -p 2222, com login por uma chave SSH do espaço de trabalho ou um token como senha. Um login acorda um sandbox pausado, e nada precisa ser instalado nele.

Em resumo
  • Sandbox.ssh_command é o comando: o id do sandbox como nome de usuário, o servidor dele, porta 2222.
  • Chaves: SetSshKeys dá ao espaço de trabalho as chaves públicas dele, que entram em todo sandbox; remover uma encerra as sessões dela.
  • Ou um token: o token de ConnectSandbox é a senha, para um programa ou um sandbox que você acessa uma vez.
  • Um shell, SFTP e túneis -L, só para dentro do sandbox, nunca para o servidor dele.

Step 1: Dê a sua chave pública ao espaço de trabalho

SetSshKeys substitui as chaves do espaço de trabalho pela lista que recebe, então envie as que ele já tem junto com a sua. As configurações do espaço de trabalho no painel fazem o mesmo, em Chaves SSH.

Python
from pathlib import Path

mine = (Path.home() / ".ssh" / "id_ed25519.pub").read_text().strip()
kept = [key.public_key for key in sandboxes.get_workspace().ssh_keys]
workspace = sandboxes.set_ssh_keys(ssh_keys=[*kept, mine])
print([key.fingerprint for key in workspace.ssh_keys])
# ['SHA256:EqzSrW++0DTmPtQLG+r1oKBoKzfKQRilcUFxx/p/Eyw']
TypeScript
import { readFile } from "node:fs/promises";
import { homedir } from "node:os";

const mine = (await readFile(`${homedir()}/.ssh/id_ed25519.pub`, "utf8")).trim();
const kept = (await sandboxes.getWorkspace()).sshKeys.map((key) => key.publicKey);
const workspace = await sandboxes.setSshKeys({ sshKeys: [...kept, mine] });
console.log(workspace.sshKeys.map((key) => key.fingerprint));
Go
home, _ := os.UserHomeDir()
mine, err := os.ReadFile(home + "/.ssh/id_ed25519.pub")
if err != nil {
	log.Fatal(err)
}
current, err := client.GetWorkspace(ctx, &sandboxes.GetWorkspaceRequest{})
if err != nil {
	log.Fatal(err)
}
keys := []string{strings.TrimSpace(string(mine))}
for _, key := range current.SSHKeys {
	keys = append(keys, key.PublicKey)
}
workspace, err := client.SetSSHKeys(ctx, &sandboxes.SetSSHKeysRequest{SSHKeys: keys})
if err != nil {
	log.Fatal(err)
}
fmt.Println(len(workspace.SSHKeys))
Rust
let mine = std::fs::read_to_string(format!("{}/.ssh/id_ed25519.pub", std::env::var("HOME")?))?;
let current = sandboxes.get_workspace(GetWorkspaceRequest::default()).await?;
let mut keys: Vec<String> = current.ssh_keys.into_iter().map(|key| key.public_key).collect();
keys.push(mine.trim().to_string());
let workspace = sandboxes
    .set_ssh_keys(SetSshKeysRequest { ssh_keys: keys, ..Default::default() })
    .await?;
println!("{}", workspace.ssh_keys.len());

Step 2: Pegue o comando SSH do sandbox

O registro de um sandbox tem o ssh_command dele. Ele só muda quando um sandbox parado inicia em outro servidor, então leia-o do registro em vez de guardá-lo.

Python
print(sandboxes.get_sandbox(sandbox_id).ssh_command)
# ssh [email protected] -p 2222
TypeScript
console.log((await sandboxes.getSandbox({ sandboxId })).sshCommand);
Go
record, err := client.GetSandbox(ctx, &sandboxes.GetSandboxRequest{SandboxID: id})
if err != nil {
	log.Fatal(err)
}
fmt.Println(record.SSHCommand)
Rust
let record = sandboxes
    .get_sandbox(GetSandboxRequest { sandbox_id: id.clone(), ..Default::default() })
    .await?;
println!("{}", record.ssh_command);
CLI
$ pethost sandbox show api-dev
id          e9bprbw1hovj6sw5
name        api-dev
state       running since 01:19
next        paused today at 01:29, unless something happens in it
size        default, disk 20 GiB
template    base@17
port 5173   https://5173-e9bprbw1hovj6sw5.sbx1.sandboxes.pethost.network
ssh         ssh [email protected] -p 2222
panel       https://console.pethost.dev/w/af6hvmyk/sandboxes/e9bprbw1hovj6sw5
used        running 6 min 17 s
created     today at 01:19
MCP
GetSandbox {"sandbox_id": "…"}

Step 3: Entre

$ ssh [email protected] -p 2222
user@e9bprbw1hovj6sw5:~$

O shell roda como user em /home/user, com sudo. Um sandbox pausado acorda quando você entra e fica acordado enquanto a sessão está aberta.

Sem chave: um token como senha

ConnectSandbox responde com um token para um sandbox, válido por uma hora, a não ser que ttl_seconds diga outra coisa, até 86.400 s, e o mesmo ssh_command: o token é a senha dele. Serve para um programa, ou para uma pessoa que acessa um sandbox uma vez. O token é root naquele sandbox: mantenha-o fora de logs e mensagens. UpdateSandbox com revoke_tokens faz todos os tokens e links criados para o sandbox pararem de funcionar.

pethost sandbox shell <id> faz tudo isso por você: ele pede um token e abre o shell no seu terminal, sem nada para configurar, e roda um comando depois de -- também em um terminal.

$ pethost sandbox shell api-dev -- uptime
 00:25:49 up 6 min,  0 user,  load average: 0.04, 0.04, 0.00

Arquivos e túneis

O mesmo endereço e a mesma porta servem scp e sftp, e encaminham portas com -L:

scp -P 2222 ./data.csv [email protected]:data/
sftp -P 2222 [email protected]
ssh -N -L 5173:localhost:5173 [email protected] -p 2222

Um túnel alcança qualquer porta do sandbox, inclusive as ligadas a localhost, então ele abre uma porta privada no seu próprio navegador em http://localhost:5173 sem token (portas e previews).

Como funciona

Nenhum servidor SSH roda no sandbox. O servidor em que ele roda responde na porta 2222: verifica a chave ou o token antes que qualquer coisa acorde, depois roda o seu shell como um processo em um terminal do sandbox, o SFTP como um programa dentro dele e um túnel direto para a porta. Ele alcança aquele sandbox e nada do próprio servidor. Um comando que você roda por SSH aparece em ListCommands enquanto roda, e o fim dele é um evento, iniciado por SSH.

  • Um login acorda um sandbox pausado, em cerca de 0,1 s. Um parado só acorda assim com wake_when_stopped; senão o login é recusado com “stopped: resume it”, e ResumeSandbox o inicia.
  • Uma sessão aberta mantém o sandbox acordado, e conta como RUNNING. Feche-a, e os timers de ociosidade começam.
  • Remover uma chave encerra as sessões dela em todos os sandboxes do espaço de trabalho.
  • Uma sessão aceita no máximo 64 variáveis do seu cliente.

Quando não funciona

  • “Permission denied (publickey,password)”: a chave não é uma das do espaço de trabalho, ou o token expirou. Adicione a chave com SetSshKeys, ou peça um token novo a ConnectSandbox.
  • “stopped: resume it”: o sandbox está parado. ResumeSandbox o inicia, com os arquivos como ele os deixou.
  • A conexão dá timeout: um firewall do seu lado bloqueia a porta 2222. Tente de outra rede, ou use pethost sandbox shell, que precisa da mesma porta.
  • O endereço não responde mais pelo sandbox: um sandbox parado iniciou em outro servidor, com um novo ssh_command. Leia-o do registro de novo.
  • Uma sessão terminou sozinha: a chave dela foi removida, ou os tokens do sandbox foram revogados.

Perguntas

Como entro em um sandbox por SSH?

Adicione a sua chave pública ao espaço de trabalho e rode o ssh_command do sandbox: ssh <sandbox id>@<server> -p 2222.

Posso usar scp e SFTP?

Sim, no mesmo endereço com -P 2222, e ssh -L encaminha as portas dele.

O SSH acorda um sandbox pausado?

Sim, no login, em cerca de 0,1 s, e a sessão aberta o mantém acordado.

Posso entrar por SSH no servidor em que um sandbox roda?

Não. Um login só alcança o sandbox dele.

Preciso instalar um servidor SSH no sandbox?

Não. O servidor do sandbox responde ao SSH e roda o seu shell dentro do sandbox.

Experimente o Pethost Agent Sandboxes

Um teste grátis de 7 dias com US$ 1 de uso e 4 vCPUs; é preciso um cartão. Depois, um plano a partir de US$ 20 por mês, que inclui esse mesmo valor em uso.

Começar o teste grátis