Run agents on a remote server over SSH

What you need

• A server you can log in to with an SSH key — TiniaCode doesn’t use password logins. No key yet? Follow Create a key below.
• A 64-bit x86 Linux server (x86_64)
• An agent installed and signed in on the server — Claude Code or Codex CLI. The agent’s sign-in stays on the server.
• Internet access on the server — if Node.js 22 is missing, TiniaCode downloads it there.

1. Add your server

1. Choose Open remote folder… from the command palette or the folder picker.
2. In the host manager, click New host.
3. Fill in "Alias (Host)", "Host address (HostName)", "Login user (User)", the port, and "Identity file (IdentityFile)". If you go through a jump server, use the advanced ProxyJump field.
4. Click Save and test connection.

TiniaCode keeps no host list of its own: it backs up your ~/.ssh/config and edits it. Servers already in ~/.ssh/config show up right away, and the app uses the same settings as the ssh command in your terminal.

2. Create a key

1. On the host screen, click Create a new key.
2. Save to record the new key as the "Identity file (IdentityFile)".
3. Click Copy the public key to the server (terminal) and type the server password once in the terminal that opens. The password only goes into the terminal — TiniaCode never sees it.

3. Check the server fingerprint on first connect

The first time you connect to a server, you’re asked to check its host key fingerprint. Compare it with the fingerprint from your server admin or cloud console, then click Verify and record the fingerprint. If they don’t match, don’t connect.

4. Open a project on the server and run agents

1. Pick the connected host and open the project folder on the server. Next time it’s one click away under "Recent projects".
2. Start an agent session and give instructions as usual.
3. The first time, TiniaCode uploads the runtime it needs to ~/.tiniacode/ssh-agent on the server. Agents run on the server, using the CLI and sign-in installed there.

Not yet available on remote projects

• Live detection of files changed outside the app on the server
• Opening the server’s web ports from your PC
• Linking sessions to the work tree, per-instruction checkpoints, reverting, and Git operations
• The Todo tab, the History tab, saved drafts, and the first-push helper
• Closing the remote terminal also ends that remote shell.

Notes do work on remote projects — they’re saved in the project folder on the server (.tiniacode/memo).

If you can’t connect

TiniaCode uses the OpenSSH installed on your PC. First check that this command logs you in without asking for a password. If it asks for one, your key isn’t registered on the server yet.

ssh your-alias

For a work server, ask your admin whether a firewall blocks the SSH port or whether you need a jump server.