Français
Menu de la documentation

Documentation Agent Sandboxes · Tâches

SSH dans une sandbox : shell, scp, SFTP et tunnels

Mis à jour le · 5 min de lecture

Chaque sandbox accepte ssh, scp, sftp et ssh -L standard : ssh <sandbox id>@<server> -p 2222, avec une clé SSH de l’espace de travail ou un token comme mot de passe. Une connexion réveille une sandbox en pause, et rien n’est à installer dedans.

En bref
  • Sandbox.ssh_command est la commande : l’ID de la sandbox comme nom d’utilisateur, son serveur, le port 2222.
  • Des clés : SetSshKeys donne à l’espace de travail ses clés publiques, qui ouvrent chaque sandbox ; en retirer une ferme ses sessions.
  • Ou un token : le token de ConnectSandbox sert de mot de passe, pour un programme ou une sandbox que vous ne joignez qu’une fois.
  • Un shell, SFTP et des tunnels -L, vers la sandbox seule, jamais vers son serveur.

Step 1: Donnez votre clé publique à l’espace de travail

SetSshKeys remplace les clés de l’espace de travail par la liste qu’on lui donne : envoyez donc celles qu’il a avec la vôtre. Les paramètres de l’espace de travail, dans la console, font la même chose, sous Clés 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: Prenez la commande SSH de la sandbox

Le registre d’une sandbox a sa ssh_command. Elle ne change que quand une sandbox arrêtée démarre sur un autre serveur : lisez-la donc dans le registre plutôt que de la garder.

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: Connectez-vous

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

Le shell tourne en tant que user dans /home/user, avec sudo. Une sandbox en pause se réveille quand vous vous connectez, et reste éveillée tant que la session est ouverte.

Sans clé : un token comme mot de passe

ConnectSandbox répond avec un token pour une sandbox, valable une heure sauf si ttl_seconds dit autre chose, jusqu’à 86 400 s, et la même ssh_command : le token est son mot de passe. Cela convient à un programme, ou à une personne qui ne joint une sandbox qu’une fois. Le token donne root dans cette sandbox : gardez-le hors des logs et des messages. UpdateSandbox avec revoke_tokens rend inutilisables tous les tokens et liens créés pour la sandbox.

pethost sandbox shell <id> fait tout cela pour vous : il demande un token et ouvre le shell dans votre terminal, sans rien à configurer, et lance aussi sur un terminal une commande donnée après --.

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

Fichiers et tunnels

La même adresse et le même port servent scp et sftp, et redirigent des ports avec -L :

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

Un tunnel atteint n’importe quel port de la sandbox, y compris ceux liés à localhost : il ouvre donc un port privé dans votre propre navigateur à http://localhost:5173, sans token (ports et prévisualisations).

Comment ça marche

Aucun serveur SSH ne tourne dans la sandbox. C’est le serveur sur lequel elle tourne qui répond sur le port 2222 : il vérifie la clé ou le token avant que quoi que ce soit ne se réveille, puis lance votre shell comme un processus sur un terminal de la sandbox, SFTP comme un programme à l’intérieur, et un tunnel directement vers le port. Il n’atteint que cette sandbox, et rien du serveur lui-même. Une commande lancée par SSH est listée par ListCommands tant qu’elle tourne, et sa fin est un événement, lancé par SSH.

  • Une connexion réveille une sandbox en pause, en 0,1 s environ. Une sandbox arrêtée ne se réveille ainsi qu’avec wake_when_stopped ; sinon, la connexion est refusée avec « stopped: resume it », et ResumeSandbox la démarre.
  • Une session ouverte garde la sandbox éveillée, et compte comme RUNNING. Fermez-la, et les délais d’inactivité commencent.
  • Retirer une clé ferme ses sessions dans chaque sandbox de l’espace de travail.
  • Une session prend au plus 64 variables de votre client.

Quand ça ne marche pas

  • « Permission denied (publickey,password) » : la clé n’est pas l’une de celles de l’espace de travail, ou le token a expiré. Ajoutez la clé avec SetSshKeys, ou demandez un token neuf à ConnectSandbox.
  • « stopped: resume it » : la sandbox est arrêtée. ResumeSandbox la démarre, ses fichiers tels qu’elle les a laissés.
  • La connexion expire : un pare-feu de votre côté bloque le port 2222. Essayez depuis un autre réseau, ou utilisez pethost sandbox shell, qui a besoin du même port.
  • L’adresse ne répond plus pour la sandbox : une sandbox arrêtée a démarré sur un autre serveur, avec une nouvelle ssh_command. Relisez-la dans le registre.
  • Une session s’est fermée toute seule : sa clé a été retirée, ou les tokens de la sandbox ont été révoqués.

Questions

Comment se connecter en SSH à une sandbox ?

Ajoutez votre clé publique à l’espace de travail, puis lancez la ssh_command de la sandbox : ssh <sandbox id>@<server> -p 2222.

Puis-je utiliser scp et SFTP ?

Oui, à la même adresse avec -P 2222, et ssh -L redirige ses ports.

SSH réveille-t-il une sandbox en pause ?

Oui, à la connexion, en 0,1 s environ, et la session ouverte la garde éveillée.

Puis-je me connecter en SSH au serveur où tourne une sandbox ?

Non. Une connexion n’atteint que sa sandbox.

Faut-il installer un serveur SSH dans la sandbox ?

Non. Le serveur de la sandbox répond en SSH et lance votre shell dans la sandbox.

Essayez Pethost Agent Sandboxes

Un essai gratuit de 7 jours avec 1 $ de consommation et 4 vCPU, avec une carte. Ensuite, une offre dès 20 $ par mois, qui inclut autant de consommation.

Démarrer l’essai gratuit