Set up Codespaces

Set up a Wallabi development environment in the cloud using GitHub Codespaces.

GitHub Codespaces runs your development environment in the cloud. You start one from the Wallabi app, which creates the branch, boots the Codespace, and wires up the credentials it needs.

This works from any operating system. Use it if you’d rather not install the toolchain locally, if you move between machines, or if you’re on Windows and want to skip setting up a Linux environment. See Getting Started on Windows for how it compares to WSL2 there.

Before You Start

You’ll need:

  • A Wallabi account with access to your app host. If you don’t have an app host yet, reach out to your Wallabi contact.
  • A GitHub account with access to your app host repository. The first time you start a session, Wallabi asks you to connect it and grant repository and Codespace access.
  • Credentials for Claude Code, either an Anthropic API key or a Claude Code OAuth token. You paste this once and Wallabi stores it as a Codespaces secret, so later sessions reuse it.

An Anthropic API key is the quickest route if you don’t already develop locally. Create one in the Anthropic Console, then paste it into the dialog.

A Claude Code OAuth token is the better choice if you’re on a Claude Pro or Max plan, because it draws on your plan rather than API credits. Generating one needs Claude Code on your own machine, so install it first if you haven’t (see Prerequisites), then run:

claude setup-token

Follow the authorization flow in your browser. The token is good for a year, and it displays only once, so copy it somewhere safe before you close the terminal.

Apart from the credentials, there’s nothing to install. The editor opens in your browser. If you’d rather work in the desktop editor, you can switch to VS Code after setup is complete.

Start an Edit Session

  1. Open your app host. In the Wallabi app, go to Hosting and select your app host.

  2. Click Start editing. The button is at the top right of the app host page.

  3. Connect your GitHub account (first time only). Your first click opens a Connect your GitHub account dialog rather than starting a session. Click Connect GitHub and authorize Wallabi on GitHub. Wallabi asks for access to your repositories and codespaces, which is what lets it create the branch and the Codespace for you.

  4. Click Start editing again. Now that GitHub is connected, the button opens the session dialog.

  5. Paste your Claude Code credentials. Pick OAuth token or API key to match what you have, then paste the value. If you’ve already set one for this repository, Wallabi keeps it. If you’ve set one for other repositories, you can reuse it here. You can also describe what you’re working on, like “Update sales dashboard filters,” which helps you recognize the session later.

  6. Click Start editing. Wallabi creates a branch from your default branch, creates the Codespace on that branch, and opens the editor in a new tab. If your browser blocks the popup, the dialog gives you an Open editor button instead.

Click Trust Folder & Continue if the editor prompts you.

Each session gets its own branch, so you’re never editing main directly. When you’re done, use the session’s actions in the Wallabi app to share or close it.

Run Your Apps

The Codespace sets up your Wallabi development environment and starts the dev server. This takes a few minutes.

Once the dev server is up, the terminal prints a link to each of your data apps. Follow one, and GitHub warns you that you’re about to access a development port served by someone’s codespace. Click Open. If the link doesn’t load, see Troubleshooting.

Then open a new terminal in the Codespace and start Claude Code:

claude

Ask it to make a small change, like renaming a section, to watch the app reload. The checks in Getting Started apply here too.

Everything runs in the Codespace, not on your own machine.

Working in Desktop VS Code

The browser editor is enough to get going. Connect desktop VS Code if you’ll be in the environment for a while: the connection is heavily optimized, so editing feels close to native.

You’ll need Visual Studio Code and the GitHub Codespaces extension. Find the extension in the Extensions panel (Cmd+Shift+X / Ctrl+Shift+X).

From the browser editor, go to File > Open in VS Code Desktop. Your browser will ask whether to let the extension open the URI. Choose Yes, and VS Code opens connected to the same Codespace.

Reopening a Session

Your session stays available after you close the editor tab. To get back to it, open your app host in the Wallabi app, go to the Edit Sessions tab, and click Open editor on the session.

Troubleshooting

These problems are specific to Codespaces. For anything else, see the general Troubleshooting page, which covers setup, dev server, Claude Code, and data issues wherever you’re working. If your browser blocks the connection to a forwarded port, start with Dev Server Issues.

The forwarded link won’t load

  • Your dev server port sometimes comes up private. Open the Ports tab next to the terminal, right-click the port, and set its visibility to Public. The link works from then on.

You’ve hit your Codespace limit

  • GitHub caps how many Codespaces you can have at once, and every session you start creates one. Delete the Codespaces you no longer need at github.com/codespaces, or close finished sessions from the Edit Sessions tab in the Wallabi app.

Setup was skipped

  • The Wallabi token didn’t reach the Codespace, so the dev server never started. Close the session from the Edit Sessions tab and click Start editing again, which is usually quickest.
  • To fix it in place instead, work through Set Up the Project in the Getting Started guide, running the commands in a Codespace terminal.

Creating a Codespace from GitHub

You can also create a Codespace directly on GitHub. Use this if Start editing isn’t available for your app host.

  1. On your app host repository in GitHub, click Code, open the Codespaces tab, then click + to create a codespace on main.
  2. Work through Set Up the Project in the Getting Started guide, running the commands in a Codespace terminal.
  3. Optionally, open the Codespace in VS Code.

Nothing provisions your secrets here, so set WALLABI_API_TOKEN and your Anthropic credentials yourself, either in your Codespaces secrets or by passing the token to setup directly. Create the Wallabi token under Settings > API Tokens in the Wallabi app, as described in Prerequisites.

This path also drops you on main rather than a session branch, so create a branch before you start making changes.

Next Steps