Quick Start¶

Go from signup to a running server with SSH access — and see it appear in billing — in about 15 minutes.

What you'll build: one compute instance, SSH-accessible, attached to your first project.

Step 1 — Create an account¶

Open app.bnerd.cloud and complete the signup form, or use the API. The request must pin the legal document versions you are accepting, so fetch the current ones first (see Authentication for what each field means):

AGB=$(curl -s https://api.bnerd.cloud/legal/agb)
NB=$(curl -s https://api.bnerd.cloud/legal/nutzungsbedingungen)
DS=$(curl -s https://api.bnerd.cloud/legal/datenschutz)

curl -X POST https://api.bnerd.cloud/create-account \
  -H "Content-Type: application/json" \
  -d '{
    "login": "you@example.com",
    "name": "Your Name",
    "password": "a-strong-password",
    "password-confirm": "a-strong-password",
    "organization_name": "My Org",
    "legal_agb_version": '"$(echo "$AGB" | jq '.data.version')"',
    "legal_agb_hash": '"$(echo "$AGB" | jq '.data.content_hash')"',
    "legal_nutzungsbedingungen_version": '"$(echo "$NB" | jq '.data.version')"',
    "legal_nutzungsbedingungen_hash": '"$(echo "$NB" | jq '.data.content_hash')"',
    "legal_datenschutz_version": '"$(echo "$DS" | jq '.data.version')"',
    "legal_datenschutz_hash": '"$(echo "$DS" | jq '.data.content_hash')"'
  }'

Check your email and click the verification link before proceeding.

Step 2 — Authenticate and get a token¶

Via the dashboard¶

Log in at app.bnerd.cloud. For automation you will want a long-lived static token — self-service token management is currently in development (roadmap #20). Contact hello@bnerd.com if you need a static token before it ships.

Via the CLI (recommended for the terminal workflow)¶

bnerd login

The interactive prompt asks for your API URL, credentials, and organization, then writes ~/.bnerd.yaml (mode 0600). Verify it works:

bnerd whoami

Via the API directly¶

curl -si -X POST https://api.bnerd.cloud/login \
  -H "Content-Type: application/json" \
  -d '{"login": "you@example.com", "password": "a-strong-password"}' \
  | grep -i '^authorization:'

TOKEN="<the JWT from the header>"

JWTs expire. For scripts and CI/CD use a static token (see Authentication).

Step 3 — Create a project¶

Projects group resources within your organization. Create one for this quickstart:

DashboardCLIAPI

Go to Projects → New Project, enter a name, and click Create.

bnerd projects create quickstart-project

The CLI prints the new project ID. Set it as the default for subsequent commands:

bnerd config set project-id <project-uuid>

ORG_ID="<your-org-id>"

curl -X POST https://api.bnerd.cloud/organizations/$ORG_ID/projects \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"project": {"name": "quickstart-project"}}'

Save the returned id as PROJECT_ID.

Step 4 — Upload an SSH key¶

You'll need an SSH public key to log in to the server.

DashboardCLIAPI

Go to SSH Keys → Add Key, paste your public key, and save.

bnerd ssh-keypairs create my-key --public-key "$(cat ~/.ssh/id_ed25519.pub)"

curl -X POST "https://api.bnerd.cloud/cloud/ssh-keypairs?project_id=$PROJECT_ID" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d "{\"name\": \"my-key\", \"public_key\": \"$(cat ~/.ssh/id_ed25519.pub)\"}"

Step 5 — Launch a server¶

DashboardCLIAPI

Go to Servers → New Server. Pick a flavor, image (e.g. Ubuntu 24.04), your keypair, and click Create. The server detail page shows the build progress.

Look up available images and flavors first:

bnerd images list
bnerd flavors list

Then create the server:

bnerd servers create web-01 \
  --flavor s.2 \
  --image ubuntu-24.04 \
  --key-name my-key

The CLI returns 202 Accepted. Poll until ACTIVE:

bnerd servers get <server-id>

# Get image and flavor IDs
curl "https://api.bnerd.cloud/cloud/images?project_id=$PROJECT_ID" \
  -H "Authorization: Bearer $TOKEN"

curl "https://api.bnerd.cloud/cloud/flavors?project_id=$PROJECT_ID" \
  -H "Authorization: Bearer $TOKEN"

# Create the server
curl -X POST "https://api.bnerd.cloud/cloud/servers?project_id=$PROJECT_ID" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "project_id": "'"$PROJECT_ID"'",
    "name": "web-01",
    "flavor_id": "<flavor-id>",
    "image_id": "<image-uuid>",
    "key_name": "my-key"
  }'

Returns 202 Accepted. Poll GET /cloud/servers/<id>?project_id=... until status is ACTIVE.

Step 6 — Get the IP address and SSH in¶

DashboardCLIAPI

On the server detail page, copy the IP address from the Addresses section.

bnerd servers get <server-id>

Look for addresses in the output.

curl "https://api.bnerd.cloud/cloud/servers/$SERVER_ID?project_id=$PROJECT_ID" \
  -H "Authorization: Bearer $TOKEN"

The addresses field maps network names to IP addresses.

SSH in using the key you uploaded:

ssh -i ~/.ssh/id_ed25519 ubuntu@<server-ip>

Default user varies by image

Ubuntu images use ubuntu, Debian uses debian, Rocky Linux uses rocky. Check the image description if you're unsure.

Step 7 — See it in billing¶

The server starts accruing usage the moment it moves to ACTIVE. To verify it appears in your billing overview:

DashboardCLI

Go to Billing → Usage — the server appears under the current billing period.

bnerd billing overview

Clean up¶

To avoid ongoing charges, delete the server when you're done with it:

DashboardCLIAPI

On the server detail page, click Delete Server and confirm.

bnerd servers delete <server-id>

curl -X DELETE "https://api.bnerd.cloud/cloud/servers/$SERVER_ID?project_id=$PROJECT_ID" \
  -H "Authorization: Bearer $TOKEN"

Troubleshooting¶

Symptom	Likely cause	Fix
Server stuck in `BUILD` > 10 min	Scheduler issue or image pull delay	Check `task_state` in the server detail; if `error` appears, delete and retry
SSH connection refused	Server still booting, or wrong IP	Wait for `status: ACTIVE` and `task_state: null`; verify you're using the correct address
SSH permission denied	Wrong key or wrong user	Confirm the keypair name was set at creation; check the default username for the image
`403 Forbidden` on API calls	Token lacks `openstack` permissions	Check your membership permissions at Settings → Members

Next steps¶

I want to…	Go to
Understand organizations and roles	Concepts
Control inbound traffic with a firewall	Per-instance firewalling
Provision object storage	Provision S3 Storage
Manage DNS for my domain	Manage DNS
Manage everything as code	Infrastructure as Code with Terraform
Browse all API endpoints	API Reference