Developer Onboard Guide

This guide is for developers joining an organization that uses a self-hosted Crafting Enterprise Edition deployment.

Step 1: Login and Set Up the CLI

  1. Open the Crafting Web Console in your browser and log in.
  2. Navigate to the Download menu and follow the instructions to install the cs CLI tool.

Note for macOS users: Do not download the CLI directly from the web browser, as macOS will quarantine the binary. Follow the instructions in the Download menu, which provide the correct installation method.

  1. Point the CLI at your organization's Crafting deployment:
cs config set server_url https://SYS-DOMAIN

Replace SYS-DOMAIN with the DNS name of your Crafting deployment. Contact your org admin if you do not know this value.

  1. Log in using the CLI:
cs login

Step 2: Set Up Access to Source Repositories

The exact steps depend on how Crafting is configured in your organization. In most cases, you will need to register an SSH public key so the workspace can check out and push code.

Visit Connect / Git in the Web Console and register the SSH public key of your Managed SSH Keypair in your GitHub (or other VCS) account.

If your org admin has enabled the GitHub App, individual SSH key registration may not be required — the GitHub App handles repository access centrally.

Step 3: Create Your First Sandbox

Create a new sandbox from an existing Template that has been prepared by your org admin. Templates contain a pre-configured, fully automated environment. Once the sandbox starts, it will automatically:

This means the sandbox is ready to use as soon as it finishes starting up, with no manual setup steps required.

Step 4: Conduct Daily Development

Connecting Your IDE

Use your preferred IDE to connect to the workspace remotely over SSH:

cs vscode      # Connect local VS Code to the workspace
cs jetbrains   # Connect a JetBrains IDE (requires Ultimate edition)
cs cursor      # Connect Cursor to the workspace
cs zed         # Connect Zed to the workspace

Alternatively, use the browser-based tools from the Web Console without installing anything locally:

To open an SSH session directly from a terminal:

cs ssh

Working Inside the Workspace

A workspace is a full Linux system. The default user is owner. Root access is available via sudo — no password required.

Install additional software as needed:

sudo apt install <package>

Managing Background Processes

Background tasks are defined as daemons in the workspace. Use the following commands to manage them:

cs ps                   # List all managed background tasks and their status
cs start <name>         # Start a daemon
cs stop <name>          # Stop a daemon
cs restart <name>       # Restart a daemon

For more details on how daemons work, see Workspace Automation.

Viewing Logs

Logs are stored in /var/log/sandbox and are automatically rotated. You can:

See Log View for details.

Step 5: Access Services via Endpoints

Services running inside a sandbox listen on a private network. To access them from a browser or an external client, an Endpoint must be used. Endpoints expose a listened port via an external DNS name secured by TLS.

Troubleshooting 502 Gateway Unavailable

If the browser shows a 502 Gateway Unavailable error when accessing an endpoint, check the following:

  1. Is the process listening on 0.0.0.0? It must listen on 0.0.0.0 (not localhost or 127.0.0.1) to accept traffic routed through the endpoint.
  2. Is the process listening on the correct port? Verify that the port matches both the workspace definition and the endpoint's backend configuration.
  3. Is the process functioning correctly? Debug the application itself to confirm it can handle incoming requests.

Step 6: Understand Auto Suspension

Development environment usage is typically spiky — active during working hours and idle the rest of the time. To avoid wasting resources, Crafting automatically suspends idle sandboxes after a configurable period.

When you are done working, disconnect from the sandbox so the system can detect it as idle and suspend it. This is a shared responsibility with your org admin for managing resource costs effectively.

If you need a sandbox to stay running for a long-running task (e.g. a build or deployment), you can Pin the sandbox from the Web Console to prevent automatic suspension.

Quick Reference

Task Command
Configure server URL cs config set server_url https://SYS-DOMAIN
Log in cs login
Show SSH public key cs secret show --user default-ssh-0
Open SSH session cs ssh
Connect VS Code cs vscode
Connect Cursor cs cursor
Connect Zed cs zed
List background processes cs ps
Start a daemon cs start <name>
Stop a daemon cs stop <name>
Restart a daemon cs restart <name>
Stream logs cs logs
Port forward cs port-forward

See Also