Browse documentation
Soda OS handbook

Make the first connection

Sign in with your own Forgejo account, then explicitly Join a Project to use its browser terminal; add a development key only if you need external SSH.

On this page

Review factory issues and pull requests through Forgejo using your own account. Admitting an agent task follows the factory walkthrough; it does not require joining a human project. The steps below establish your separate access for manual development and intervention.

Obtain the connection information

Your operator supplies the Soda HTTPS URL, Forgejo identity/onboarding details and the approved LAN or Tailnet route. Browser origins, the host's operator SSH address, Forgejo's Git endpoint and each project's IP are different endpoints. Do not substitute one for another.

For cloud access, connect your client to the permitted Tailnet. Direct Project SSH or service access also needs the operator's approved project-subnet route; browser-terminal access uses the appliance's browser origin. See Tailscale.

Trust the browser endpoints and sign in

Open the exact Soda HTTPS URL. Check an unexpected certificate or hostname with your operator before entering credentials. For a private certificate authority, install the verified CA through your client's normal trust mechanism. Do not disable browser or CLI TLS checks to bypass a warning.

Select Sign in and complete Forgejo's login, initial password change, MFA and consent as applicable. You return to Soda as your Forgejo identity. Use a private channel for an initial password; never paste it into a project or issue.

Join and open a browser terminal

Open the environment you intend to use and select Join project. Current repository code-write permission is required. The repository owner must Join too. Choose account-only access if you do not need external SSH keys, wait for native provisioning to complete, then open a browser terminal. Verify whoami and $HOME refer to your own Project account. See Projects and workspaces.

Joining creates your Project account; merely signing in or observing a Project does not grant execution. A browser terminal needs neither a client SSH key nor a direct client route to the Project subnet.

Add an optional public development key

Use an existing personal SSH key or create one on your client:

ssh-keygen -t ed25519

Choose a passphrase and an unused filename; do not overwrite an existing key. Keep the private file on that client. Open your Soda Profile, find the public development-access keys and register only the .pub file's contents. Check the resulting fingerprint.

These keys are installed when you explicitly select them during Join or apply them through that Project's access controls. They are not your Git-host key registry, and profile edits do not synchronize existing Project accounts. See People and access.

Obtain the external SSH connection details

After Join and explicit key installation, use the Project's connection details: your project-local login, current IP and public SSH host key. Have the operator confirm your client route to that subnet before testing SSH.

PROJECT_USER and PROJECT_IP below mean those displayed values. An example IP in documentation is not the address of your installation.

Verify and test SSH

Compare the first SSH prompt with the project's public host-key fingerprint obtained through the trusted dashboard or your operator. If the page supplies the public key rather than a fingerprint, save that public key to a file on your client and inspect it with ssh-keygen -lf PROJECT_HOST_KEY.pub.

Connect using the corresponding personal private key:

ssh -i /path/to/personal_private_key PROJECT_USER@PROJECT_IP

Accept only a matching identity. A later unexpected host-key change needs investigation, not disabled checking or blind deletion of a known-host entry. The operator can verify a project's public key through native host access.

In the session, whoami should show your project-local login and $HOME your own project home. Commands and transfers use the same native account:

ssh PROJECT_USER@PROJECT_IP 'whoami; printf "%s\n" "$HOME"'
scp ./local-file PROJECT_USER@PROJECT_IP:~/
sftp PROJECT_USER@PROJECT_IP

Use -i or your client SSH configuration if the desired key is not selected by default. Connect your editor and clone with your own Git credentials. Project access does not require a host account or developer login to Cockpit.

If access fails

  • Timeout or no route: check the actual client route, project state and private firewall policy with the operator. Do not open public ingress.
  • Permission denied: confirm the displayed login, selected key and completed join. A network error is not an authentication decision.
  • Browser works, Git fails: use the repository's real clone URL and separate Git key/permission, not the project SSH endpoint.
  • Unavailable environment: preserve the diagnostic and ask the operator to inspect it; do not create a replacement to recover files.