{"id":51598982,"url":"https://github.com/e2b-dev/e2b-terminal-starter","last_synced_at":"2026-07-11T20:31:00.435Z","repository":{"id":370632285,"uuid":"1279637585","full_name":"e2b-dev/e2b-terminal-starter","owner":"e2b-dev","description":"a starter repo to type in e2b terminals. terminals terminals terminals!","archived":false,"fork":false,"pushed_at":"2026-07-09T23:29:56.000Z","size":132,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-07-10T01:09:45.751Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/e2b-dev.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-06-24T22:00:15.000Z","updated_at":"2026-07-09T23:30:00.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/e2b-dev/e2b-terminal-starter","commit_stats":null,"previous_names":["e2b-dev/e2b-terminal-starter"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/e2b-dev/e2b-terminal-starter","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/e2b-dev%2Fe2b-terminal-starter","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/e2b-dev%2Fe2b-terminal-starter/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/e2b-dev%2Fe2b-terminal-starter/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/e2b-dev%2Fe2b-terminal-starter/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/e2b-dev","download_url":"https://codeload.github.com/e2b-dev/e2b-terminal-starter/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/e2b-dev%2Fe2b-terminal-starter/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35375152,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-11T02:00:05.354Z","response_time":104,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-07-11T20:30:55.737Z","updated_at":"2026-07-11T20:31:00.403Z","avatar_url":"https://github.com/e2b-dev.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# E2B Terminal Starter\n\nA Next.js starter for building apps that run user commands inside E2B sandboxes.\n\nThe app gives each local user multiple terminal conversations. Each conversation is backed by one E2B sandbox, stores command history in SQLite, and reconnects to the same sandbox when the user returns.\n\nRequires Node.js 20.19 or newer and pnpm 10.\n\n## Stack\n\n- Next.js App Router\n- E2B Sandbox SDK\n- Ghostty Web terminal renderer\n- SQLite with `better-sqlite3`\n- Local signed-cookie session for starter auth\n\n## Run with Stripe Projects\n\nThis template is designed for `stripe projects build` with the `e2b/sandbox` service.\n\n```bash\nstripe projects build e2b/terminal-starter\ncd e2b-terminal-starter\nstripe projects env --pull\npnpm install\npnpm dev\n```\n\nOpen http://localhost:3000.\n\n`stripe projects env --pull` writes the E2B credentials provisioned by Stripe Projects into your local environment file.\n\n## Run without Stripe Projects\n\nYou can also run the app with your own E2B API key.\n\n```bash\npnpm install\ncp .env.example .env.local\n```\n\nSet `E2B_API_KEY` in `.env.local`, then start the app:\n\n```bash\npnpm dev\n```\n\n## Environment\n\nRequired:\n\n```bash\nE2B_API_KEY=e2b_...\n```\n\nOptional:\n\n```bash\nE2B_TEMPLATE=base\nE2B_TIMEOUT_MS=300000\nAPP_DATABASE_PATH=./data/app.db\nAPP_SESSION_SECRET=change-me\nAPP_ENABLE_LOCAL_AUTH=\n```\n\n`E2B_TIMEOUT_MS` controls sandbox create/connect calls and PTY command execution. New sandboxes are created with `autoResume: true` and `onTimeout: \"pause\"`.\n\n`APP_SESSION_SECRET` signs the local starter session cookie. Set it in deployed or shared environments.\n\n`APP_ENABLE_LOCAL_AUTH` controls the starter's name-based auth flow. It is enabled by default in development and disabled by default in production. Do not enable it for a shared deployment unless you understand that anyone who can reach the app can claim a local user name and run commands with your E2B API key.\n\n## How It Works\n\nThe server stores starter state in SQLite:\n\n- `users`: local users keyed by UUID\n- `conversations`: one user's terminal conversations\n- `sandboxes`: one E2B sandbox per conversation\n- `messages`: command and output history\n\nSelecting a new local user creates an empty conversation, but no E2B resources are used yet. The first command creates and attaches a sandbox; later commands reconnect to that same sandbox, start a short-lived PTY, send the command through Bash, and record the output in SQLite.\n\nIdle sandboxes pause automatically. The next command reconnects with E2B auto-resume enabled.\n\nUse `Cmd+Enter` on macOS or `Ctrl+Enter` elsewhere to run the command from the editor.\nCommands are limited to 16,000 characters, and the terminal keeps the first 256,000 characters of output from each run.\n\n## Customize the Starter\n\nThe code is split around the parts most applications replace:\n\n| Change                                       | Start here                                 |\n| -------------------------------------------- | ------------------------------------------ |\n| Use Clerk, Auth.js, or another auth provider | `lib/auth.ts` and `app/api/users/route.ts` |\n| Change environment defaults or limits        | `lib/config.ts`                            |\n| Change the SQLite schema or queries          | `lib/db/`                                  |\n| Change sandbox creation and lifecycle        | `lib/e2b/sandbox.ts`                       |\n| Change how commands run through the PTY      | `lib/e2b/pty.ts`                           |\n| Add work around command execution            | `lib/run-command.ts`                       |\n| Change client loading and selection behavior | `app/use-terminal-app.ts`                  |\n| Change a visible part of the interface       | `app/components/`                          |\n\nAPI request and response types live in `lib/contracts.ts`. Browser requests are collected in `app/api-client.ts`, so changing an endpoint does not require searching through UI components.\n\nThe database layer uses plain `better-sqlite3` functions instead of an ORM. `lib/db/client.ts` owns setup and schema migrations; the other files contain queries grouped by domain.\n\n## Checks\n\n```bash\npnpm test\npnpm typecheck\npnpm format:check\npnpm build\n```\n\nFor a live E2B smoke, create two conversations and verify that each keeps an independent working directory. Run commands that produce normal output, no output, and a non-zero exit code; then pause a sandbox and confirm the next command reconnects successfully.\n\n## Starter Auth\n\nThis repo intentionally uses a local name field instead of production authentication. It is enough to show user-owned conversations and sandbox mapping on your machine.\n\nThe local auth endpoint is enabled by default in development and disabled by default in production. Replace it with Clerk, Auth.js, or your own auth provider before shipping a real app.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fe2b-dev%2Fe2b-terminal-starter","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fe2b-dev%2Fe2b-terminal-starter","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fe2b-dev%2Fe2b-terminal-starter/lists"}