Skip to content

Working with Workspaces

This guide walks through the full workspace lifecycle: launching, connecting to the terminal, opening the browser IDE, and cleaning up. For background on what workspaces are and how credentials work, see the Workspaces service reference.

Prerequisites

  • An account with access to at least one project.
  • The bnerd CLI installed and authenticated (bnerd login). See the CLI guide for installation.
  • To clone a private git repository: a git PAT configured in Account Settings.

1. Launch a workspace

Dashboard

  1. Open a project in the dashboard.
  2. Go to Workspaces in the left navigation.
  3. Click New workspace.
  4. In the launch modal, configure:
  5. Target cluster — the cluster your kubectl inside the pod will point at.
  6. Runtime cluster — where the workspace pod runs (shown when more than one runtime cluster is available for your project; otherwise auto-selected).
  7. Access preset — the credential set and API token scope for the session:
    • Read-only: kubeconfig + read-only API token (no clone).
    • Reporting: read-only + git clone.
    • Developer: kubeconfig + git clone + read/write API token (clamped to your permissions).
  8. TTL — how long the workspace should live. The modal shows only TTL options within your org's ceiling; the expiry is displayed as you select.
  9. Source (optional) — a git repository to clone into the pod. If you select a repo and have no git PAT for that host, the modal shows a link to Account → Git tokens.
  10. Egress CIDRs (optional, Network section) — outbound CIDRs to allow from the pod. Pods are egress default-deny; add 0.0.0.0/0 for full internet access or specific CIDRs for internal network access only.
  11. Click Launch.

The workspace appears in the list as Provisioning, then flips to Active once the pod is running (usually under 30 s).

CLI

# Minimal launch (uses the project set in ~/.bnerd.yaml or --project-id)
bnerd workspace launch --target-cluster dev01

# With a custom TTL and a git repository
bnerd workspace launch --target-cluster dev01 --ttl 2h --repo main

# Developer preset (read/write API token + git clone, clamped to your permissions)
bnerd workspace launch --target-cluster dev01 --preset developer --repo main

# Open egress to a private network CIDR
bnerd workspace launch --target-cluster dev01 --egress-cidr 10.0.0.0/8

# Full internet egress
bnerd workspace launch --target-cluster dev01 --egress-cidr 0.0.0.0/0

# List all workspaces in the project
bnerd workspace list

workspace launch submits the request and returns the workspace ID and status. Use workspace get <id> to poll until the status is active.

Output formats: add -o json or -o yaml for scripting.

2. Open a terminal

CLI — workspace create (launch + attach in one step)

bnerd workspace create --target-cluster dev01

This launches the workspace, waits for the pod to be ready (up to 3 min), then drops you directly into the pod's shell — like ssh, but routed securely through the platform without opening any public network path to the pod.

Detach by exiting the remote shell (exit or Ctrl-D). The workspace keeps running until the TTL elapses or you revoke it.

# Scripting: launch only, no terminal
bnerd workspace create --target-cluster dev01 --no-attach

CLI — attach to an existing workspace

bnerd workspace attach <workspace-id>

You can reconnect to an active workspace at any time. Terminal access is restricted to the user who launched the workspace.

Dashboard

  1. Open the workspace list under Workspaces in the project.
  2. Click the workspace row to open its detail view.
  3. In the Dock at the bottom of the screen, click Open terminal.

The terminal opens in a panel docked to the bottom of the dashboard.

3. Work inside the pod

Once you are in the pod's shell, your environment is pre-configured:

bnerd CLI

The bnerd CLI is installed and configured as you, with a read-only API token scoped to your project and TTL-bound to the workspace:

bnerd projects list          # list your projects
bnerd workspace list         # list workspaces in the project
bnerd k8s clusters list      # list registered clusters

The token expires when the workspace expires. It is read-only by default; write operations via the CLI from inside the pod are not permitted.

kubectl

KUBECONFIG is set to a scoped kubeconfig for the project's target cluster:

kubectl get pods -n my-namespace
kubectl get nodes

Access is read-only and namespace-scoped to the project namespace.

git

If you launched with --repo, the repository is cloned at /workspace/<repo-name> using your personal git PAT. The PAT is available for subsequent clone and pull operations via the standard git credential helper:

cd /workspace/my-repo
git log --oneline -10
git pull

4. Open the browser IDE

For a full editing environment without leaving the browser, use the built-in IDE (OpenVSCode Server running inside the pod):

  1. In the dashboard, open the workspace detail view.
  2. In the Dock, click Open editor (next to Open terminal).
  3. A new browser tab opens at the IDE, proxied through the platform — no public network path to the pod is opened.

The IDE runs with the same workspace credentials as the terminal. File changes inside the pod are visible immediately in both the terminal and the editor (same filesystem).

New tab, same origin

The editor opens at the platform's own domain in a top-level browser context, not an embedded iframe. Authentication uses a short-lived first-party cookie — no special browser configuration is required.

5. Inspect a workspace

CLI

# Human-readable table
bnerd workspace get <workspace-id>

# Full detail as JSON
bnerd workspace get <workspace-id> -o json

The output includes: workspace ID, status, TTL, expiry time, target cluster, and credential types issued.

Dashboard

Click any workspace row in the Workspaces list to open the detail panel, which shows the same information plus the credential audit trail.

6. Revoke a workspace

Revoking a workspace tears down the pod immediately and invalidates all credentials — kubeconfig, API token, and git credential — before the TTL elapses.

CLI

# Interactive confirmation (prompts you to type the workspace ID)
bnerd workspace revoke <workspace-id>

# Skip the confirmation prompt (for scripting)
bnerd workspace revoke <workspace-id> --yes

Dashboard

  1. Open the workspace detail view.
  2. Click Revoke and confirm the action.

Revoke is permanent

There is no undo. The pod is destroyed, the kubeconfig is invalidated, and the API token is revoked. Any unsaved work in the pod is lost.

Set up a git PAT for cloning

To clone private git repositories into a workspace, add a personal access token for the git host in your account settings. You only need to do this once per git host.

  1. Go to Account → Git tokens (top-right profile menu, or navigate to /account/git-tokens).
  2. Click Add git token.
  3. Fill in: | Field | Example | |-------|---------| | Provider | gitlab | | Host | git.bnerd.net | | Token | glpat-… | | Name | my-bnerd-pat |
  4. Click Save. The platform validates the token against the host.

When launching a workspace with --repo and the repository lives on a host for which you have a PAT, the PAT is automatically included as the clone credential. If no PAT is found for the repository's host, the launch is rejected with an error message pointing here.

Troubleshooting

Symptom Likely cause Fix
bnerd workspace create times out Pod not starting within 3 min Check the cluster has capacity; revoke and retry
workspace attach returns "not active" Workspace expired or was revoked Launch a new workspace
Clone fails with authentication required No git PAT for the repo's host Add a PAT under Account → Git tokens
bnerd projects list returns 401 inside the pod Token expired (workspace past TTL) Revoke and launch a new workspace
Launch rejected: "No git PAT for …" Missing PAT for the repo host Add a PAT under Account → Git tokens
Launch rejected: "concurrent workspace cap reached" Org limit reached Revoke an existing workspace first
Launch rejected: "cluster not in allowed list" Your org has no permitted target clusters Contact hello@bnerd.com — clusters are allow-listed per org by a platform admin
TTL rejected as too long Org max_ttl_seconds ceiling reached Your org's default max TTL is 1 h; contact support to raise it

CLI reference

All workspace commands live under bnerd workspace (aliases: bnerd workspaces, bnerd ws).

bnerd workspace
  create    Launch a workspace and drop into its terminal (launch + attach)
  launch    Submit a launch request (does not attach)
  attach    Attach an interactive terminal to an existing active workspace
  list      List workspaces in the current project
  get       Show details of a workspace
  revoke    Tear down a workspace and invalidate all its credentials

Flags

Command Flag Default Description
create, launch --target-cluster — Target cluster ref — the cluster kubectl points at (required)
create, launch --runtime-cluster auto Runtime cluster ref — where the pod runs (defaults to the first available)
create, launch --ttl 1h Workspace TTL (30m, 2h, 7200s)
create, launch --preset — Access preset: read_only or developer (developer = kubeconfig + git clone + read/write token, clamped to your rights)
create, launch --repo — Git repo ref to clone into the pod
create, launch --namespace auto Override the pod namespace (must match ws-*)
create, launch --credential-types (preset) Comma-separated credential types to mint; overrides the preset
create, launch --scope (preset) Repeatable: in-pod API token scope, e.g. --scope projects:write. Clamped server-side to your permissions. Overrides the preset.
create, launch --egress-cidr — Repeatable: outbound CIDR to allow from the pod, e.g. --egress-cidr 0.0.0.0/0
create, launch --cluster-access own_namespace Kubernetes access scope: own_namespace, namespaced, or cluster (clamped to your grant's max level)
create, launch --cluster-namespaces — Repeatable: namespace to grant access to when --cluster-access=namespaced
create --no-attach false Launch only; skip the terminal attach (for scripting)
revoke --yes false Skip the interactive confirmation prompt
all -o / --output table Output format: table, json, yaml

TUI

The interactive TUI (bnerd x) includes a Workspaces view:

  • Press :projects to select a project, then :ws (or :workspaces) to open the Workspaces view.
  • The list shows workspaces with health-coloured status indicators.
  • By default the list shows active workspaces plus those that expired in the last 24 hours.
  • Key bindings inside the Workspaces view:
Key Action
n or c Launch a new workspace (opens launch form)
Enter or i Inspect selected workspace (detail view)
a Attach terminal to selected workspace (active workspaces only)
x Revoke selected workspace (with confirmation)
f Cycle status filter: active+recent → active → expired → revoked → all

What's next

Task Where
Install and configure the CLI CLI guide
Understand workspace credentials Workspaces service reference
Add a git PAT Account → Git tokens (/account/git-tokens)
Deploy a Kubernetes cluster Deploy a Kubernetes Cluster