~/sursakit

// docs

User journey

A full walkthrough of using Sursakit on a real project.

1. Sign in

  1. Open the app.
  2. Authenticate with email + password, Google, or GitHub. (GitLab and Bitbucket are connected later for service imports — they aren't sign-in providers.)
  3. You land on the dashboard with your default organization selected.

2. Create a workspace

  1. Click New workspace.
  2. Name it.
  3. Add services:
    • Import your backend repo from GitHub.
    • Import your frontend repo.
    • Add a Postgres database from the template.
  4. Confirm — the workbench opens on the main session.

3. Boot the services

  1. Click Run all.
  2. The runtime containers start. Logs stream in the bottom panel.
  3. Application services expose a Preview URL behind Traefik.

4. Edit code

  1. Expand a service in the file explorer.
  2. Open a file — it connects to a language server running in the workspace.
  3. Save. The runtime hot-reloads if your service is set up for it.

5. Open a terminal

  1. In the bottom panel, click + next to Terminals.
  2. Pick the service to attach to.
  3. A real PTY opens inside the running container. Run migrations, REPLs, ad-hoc commands.

6. Branch into a feature session

  1. Open the session switcher.
  2. Create a new session, e.g. feature/checkout-redesign, branched from main.
  3. The new session has its own runtime state — your changes don't disturb main.

7. Commit and open a PR

  1. Open the Version Control panel.
  2. Review the working diff. Use Generate commit message if you want an AI draft.
  3. Commit. Push.
  4. Open a pull request against your remote.

8. Hand a task to Codex

  1. Open the chat panel.
  2. Describe the change ("Add Stripe webhook handler for invoice.paid").
  3. Codex spins up its own session, runs your services, edits files, and commits.
  4. When it finishes, it opens a pull request you can review in the workbench.

9. Merge and move on

  1. Review the diff and the conflict editor if needed.
  2. Merge the PR.
  3. Delete the session if you're done with it — sessions are disposable.

Quick notes

  • Use the Preview (eye) icon to open application services in the browser.
  • Sessions persist their runtime; you can come back later and the containers will still be there.
  • Codex never reaches beyond skills you've enabled in the workspace.