Connect and exec

connectCopy Anchor Link

kvbox connect <name>
kvbox connect <name> -- <cmd>

connect opens a shell in the box over SSH, with your terminal. A stopped box is started first, a paused one resumed, a hibernated one woken. Through a control plane the SSH session goes to the host's public address and the box's own port; your access is a short-lived SSH certificate the CLI renews on its own.

execCopy Anchor Link

exec is the scripted surface: one command, its exit code comes back, stdin and stdout flow through. It mirrors boxd machine exec, so scripts written for one work with the other.

kvbox exec dev -- ls /app                         # -- separates the box from the command
kvbox exec dev -- 'cd /app && npm test'           # pipes, &&, redirects and cd work: quote them
kvbox exec dev -e API_KEY=xxx -e DEBUG=1 -- env   # environment variables (-e or --env, repeatable)
kvbox exec dev --timeout 30 -- ./slow-thing       # killed after 30 s, exit 124
kvbox exec dev --tty -- htop                      # pseudo-terminal for interactive tools
kvbox exec dev --json -- make                     # {"output": "...", "exit_code": N}

The command's exit status is kvbox exec's exit status, so this does what it says:

kvbox exec dev -- 'test -f /app/ready' && deploy

Stdin is forwarded whenever it is not a terminal, and its end of file reaches the command:

cat data.json | kvbox exec dev -- 'cat > /tmp/data.json'
tar -cf - ./src | kvbox exec dev -- 'tar -xf - -C /app'

Like connect, exec resumes or wakes a sleeping box on its own.