Mobicode is a self-hosted, mobile-first coding-agent API. It is a single Go binary with a GraphQL API, SQLite persistence, and a single mobile-owned Nostr identity.
- GraphQL API at
/graphql - SQLite with embedded, versioned migrations run by
cmd/migrations - NIP-98 signed HTTP authentication using a secp256k1/BIP-340 Nostr key
- Browser setup wizard, encrypted GitHub connection, and secret-token console
- Explicit database migration command and
mobicode serveworkflow
- Go 1.26 or later
- A C compiler with CGO enabled (required by SQLite)
git clone https://github.com/soumajitgh/mobicode.git
cd mobicode
make dev-setup
make dev-runIn another terminal:
make mobile-dev
# or: pnpm mobile-devmake dev-setup creates ignored .env and mobile/.env files with a random
console secret and one matching disposable Nostr identity. make dev-run
applies migrations before starting the Go API. On a fresh development database,
the configured development identity becomes the owner automatically, so the
mobile can call GraphQL immediately without completing browser onboarding.
The command refuses to replace existing local configuration. For a physical phone, use the development machine's LAN address on the first run:
make dev-setup DEV_HOST=192.168.1.20Simulators can use the default localhost. The Go server listens on all network
interfaces; the host in PUBLIC_BASE_URL and EXPO_PUBLIC_GRAPHQL_URL must
still match exactly because NIP-98 signs the absolute request URL.
The initial setup flow intentionally follows an open-first-visitor model. Do
not expose /welcome on a public server before the owner is ready to pair it.
Configuration comes from environment variables or an optional .env file
passed with --config.
| Variable | Default | Description |
|---|---|---|
PORT |
8080 |
HTTP server port |
ENV |
development |
Runtime environment; use production for JSON logs |
DATABASE_PATH |
data/app.db |
SQLite database path |
PUBLIC_BASE_URL |
http://localhost:<PORT> |
Canonical public API origin used in NIP-98 request binding; must be HTTPS in production |
DEV_NSEC |
— | Optional disposable development owner; rejected outside development |
SECRET_TOKEN |
— | Required 32+ character secret for /console/login and GitHub App credential encryption |
Run go run ./cmd/migrations --config .env (or make init) before starting
the API. The migration command embeds and applies the SQL files in
cmd/migrations/; the API never changes the schema on startup and refuses to
start without the console token.
After setup, visit /console/login and enter SECRET_TOKEN. The
console session lasts 24 hours and currently exposes Git providers in the
left sidebar. Connecting GitHub creates a private GitHub App owned by the user;
they choose which repositories to install it on. The generated private key,
client secret, and webhook secret are encrypted in SQLite. Keep SECRET_TOKEN
stable for the lifetime of the database.
For local setup testing, use make dev and open /welcome. Stop the server with
Ctrl-C, reset its identity when needed, then run make dev again.
All GraphQL requests require Authorization: Nostr <base64-signed-event>. The
mobile signs the exact POST body, URL, and method; the server rejects invalid,
expired, unauthorized, or replayed proofs. viewer returns the configured
public key.
Set EXPO_PUBLIC_GRAPHQL_URL to PUBLIC_BASE_URL plus /graphql when running
the mobile app. The origins must match exactly for NIP-98 request binding. The
private nsec is kept in Expo SecureStore and unlocked with the device's
configured biometric/device authentication.
To replace a lost or compromised mobile key, stop the server and run:
go run ./cmd/mobicode identity reset --confirm --config .envUse make dev-run for the dependency-light local server. Use make dev when
Air is installed and hot reload is desired; both commands apply migrations and
seed development data first. The default GitHub seed uses clearly marked dummy
values so provider-dependent UI works immediately. Start Expo separately with
make mobile-dev; it installs mobile
dependencies automatically on a fresh checkout. Once installed, the root-level
pnpm mobile-dev shortcut is also available. Use make mobile-ios,
or make mobile-android to launch a specific native platform.
For a running Android emulator or USB-connected device, the mobile helpers
automatically reverse port 8080 through ADB. This lets Android reach the Go
API at localhost while keeping the URL used by NIP-98 signing unchanged.
Run plain make to see the focused development command menu.
Verify the complete authenticated path at any time:
make dev-queryThis requests viewer and gitProvider through the same URL-, method-, and
body-bound NIP-98 authentication enforced for the mobile client.
To use a real development GitHub App instead of the dummy seed, set the
DEV_GITHUB_* values documented in .env.example, then run:
make dev-seed FORCE=1Without FORCE=1, the seed is idempotent and preserves any GitHub provider
configured through the browser flow. Development seed variables are rejected
when ENV is not development.
The GitHub App manifest intentionally omits webhooks because MobiCode does not
consume GitHub events yet. This keeps the complete App creation and installation
flow usable with a localhost PUBLIC_BASE_URL, without a tunnel. For a physical
mobile device, set PUBLIC_BASE_URL to the development machine's reachable LAN
address; simulators can continue using localhost.
Generate typed mobile GraphQL documents after changing the schema or an
operation with make mobile-codegen. During operation development, use
make mobile-codegen-watch. Run make mobile-dev-check for TypeScript and
make mobile-export to verify the Expo production export.
Mobile UI primitives live under mobile/src/components/ui. Add gluestack
components with pnpm --dir mobile ui:add <component>; the checked-in
gluestack-ui.config.json keeps generated components in that directory.
For testing the real browser onboarding flow, leave DEV_NSEC and
EXPO_PUBLIC_DEV_NSEC empty and open /welcome. The development-only
Continue without mobile option remains available after connecting GitHub.
go test ./...
go run github.com/99designs/gqlgen generate
go run github.com/a-h/templ/cmd/templ generate
go build ./cmd/mobicodeThe Expo/React Native client, when present, lives independently in
mobile/.
Issues and pull requests are welcome. Keep changes focused, add tests for
behavior changes, and run go test ./... before opening a pull request.
For security vulnerabilities, use GitHub's private security advisory form.