Skip to content
Gortexa

Quickstart with AI

Gortexa lets a coding agent with terminal and file-system access quickly create a runnable, contract-first API prototype: proto, gRPC, HTTP/JSON, MCP, validation, and server wiring are generated together. To use the framework packages as a plain library instead (no scaffolded project), see Use as a module.

Prerequisites

Section titled “Prerequisites”
  • The agent can run shell commands and read/write the local project.
  • Go 1.21+ (as the bootstrap; the framework downloads Go 1.26.5), Git, curl, OpenSSL, and Perl are installed, and GitHub plus the Go module proxy are reachable.
  • The shell may use GOTOOLCHAIN=auto so Go can download the toolchain required by the framework.
  • Start with an empty workspace. The agent must not overwrite projects, push, deploy, or commit secrets unless you explicitly authorize it.

Paste this: create a reliable prototype

Section titled “Paste this: create a reliable prototype”

This prompt builds the toolchain, CLI, and project layout from the same verified release tag. That avoids drift between an @latest CLI and a floating main layout. It records the checkout SHA and avoids make bootstrap inside the generated project because the toolchain is already installed from the framework checkout.

Help me create a runnable Gortexa prototype, not a production service. If I have
not supplied SERVICE_NAME, GO_MODULE, API_DOMAIN/API_VERSION, and ENTITY, ask only
for those four values first. Do not overwrite an existing directory, git push,
deploy, commit, or reveal any secret.
Execute the following steps in one shell session, in order, and report each result.
Run set -euo pipefail first; stop on any failure rather than guessing or skipping it.


set -euo pipefail
WORKSPACE="$HOME/src"
SERVICE_NAME="myapp"
GO_MODULE="github.com/me/myapp"
API_DOMAIN="billing"
API_VERSION="v1"
ENTITY="Invoice"
FRAMEWORK_REF="v0.27.0"  # change only after testing a newer release
FRAMEWORK="$WORKSPACE/gortexa-framework"
PROJECT="$WORKSPACE/$SERVICE_NAME"


1. mkdir -p "$WORKSPACE"
   git clone --depth 1 --branch "$FRAMEWORK_REF" https://github.com/yshengliao/gortexa.git "$FRAMEWORK"
   cd "$FRAMEWORK"
   export GOTOOLCHAIN=auto
   bash install.sh
   export PATH="$(go env GOPATH)/bin:$PATH"
   mkdir -p "$FRAMEWORK/bin"
   go build -o "$FRAMEWORK/bin/gortexa" ./cmd/gortexa
   export PATH="$FRAMEWORK/bin:$PATH"
   CLI="$FRAMEWORK/bin/gortexa"
   "$CLI" doctor
   FRAMEWORK_COMMIT="$(git rev-parse HEAD)"
   printf 'framework ref=%s commit=%s\n' "$FRAMEWORK_REF" "$FRAMEWORK_COMMIT"


2. "$CLI" create "$PROJECT" --module "$GO_MODULE" --repo "file://$FRAMEWORK" --ref "$FRAMEWORK_REF"
   cd "$PROJECT"
   Without printing the old value, reset the JWT secret written by create to the
   placeholder that refuses startup:
   perl -0pi -e 's/(jwt_secret:\s*")[^"]*(")/${1}dev-only-insecure-secret-change-me-please${2}/' etc/config.yaml
   grep -Fq 'jwt_secret: "dev-only-insecure-secret-change-me-please"' etc/config.yaml
   Read all four skill files under .skills/ before changing code.
   Do not run make bootstrap in this new project; reuse the toolchain verified above.


3. "$CLI" gen "$API_DOMAIN/$API_VERSION" "$ENTITY"
   Run go build ./... && go test -race ./... && go vet ./...
   Explain that generated logic is an in-memory prototype stub and identify what
   must be replaced for a real service.


4. For a local prototype only, generate a short-lived runtime secret. To clean up
   reliably from one shell, start the generated server binary directly ("$CLI" run
   is the foreground development command):
   export GORTEXA_AUTH__JWT_SECRET="$(openssl rand -hex 32)"
   go build -o "$PROJECT/.gortexa-prototype-server" ./cmd/server
   "$PROJECT/.gortexa-prototype-server" >"$PROJECT/gortexa-prototype.log" 2>&1 &
   SERVER_PID=$!
   cleanup() { kill -TERM "$SERVER_PID" 2>/dev/null || true; wait "$SERVER_PID" 2>/dev/null || true; rm -f "$PROJECT/.gortexa-prototype-server" "$PROJECT/gortexa-prototype.log"; }
   trap cleanup EXIT INT TERM
   for _ in $(seq 1 60); do
     if curl -fsS http://127.0.0.1:8080/healthz >/dev/null 2>&1; then break; fi
     sleep 0.5
   done
   curl -fsS http://127.0.0.1:8080/healthz
   test "$(curl -sS -o /dev/null -w '%{http_code}' http://127.0.0.1:8080/v1/resources/x)" = 401
   curl -fsS -X POST localhost:8080/mcp -H 'Content-Type: application/json' \
     -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
   cleanup
   trap - EXIT INT TERM


5. Stop after prototype verification. Do not git add or build a Docker image until
   I confirm that etc/config.yaml remains a placeholder, secrets are externalized,
   and persistence plus authorization are done.


Rules: proto is the single source of truth; after proto changes run "$CLI" regen;
never hand-edit gen/. Read https://gortexa.sheng.page/llms.txt first, then only
the documentation pages needed for the task.

Success means doctor, build, race tests, and vet pass; healthz returns 200; an unauthorized HTTP-gateway request returns 401; and MCP tools/list exposes the generated tool. That validates the development scaffold, HTTP auth surface, and MCP discovery. It does not perform a live gRPC E2E test or complete the data and authorization models.

Paste this: plan a production foundation

Section titled “Paste this: plan a production foundation”

Use this when you intend to ship the service. It forces the agent to collect the inputs that materially change the design instead of guessing tenants, authorization, or retention rules.

Move the current Gortexa prototype toward a production foundation, but do not
write code yet. First confirm: actors and tenant model, role/permission matrix,
database and migrations, transactions/idempotency/pagination, cache/MQ retry and
DLQ semantics, secret rotation, TLS ingress/trusted proxies/rate limits,
SLOs/observability, replicas/readiness, rollback, and acceptance tests.


Ownership must be derived from an authenticated principal/tenant, never trusted
from an owner value in the request body. After I answer, propose a phased plan;
do not retain generated in-memory logic as the production implementation. Include
external secret injection, persistent repositories/migrations, tenant-aware
authorization, real readiness, cross-tenant negative tests, integration/E2E/failure
tests, a non-root Docker runtime, and TLS-ingress verification. Run tests after
each phase and report remaining risks.

See Deployment and Security & boundaries.

Skills and agent docs

Section titled “Skills and agent docs”

Every gortexa create project contains .skills/:

Skill It helps with It does not replace
bootstrapping-environment Installing and checking the pinned toolchain release and production readiness
scaffolding-projects Creating the fixed project layout product requirements and an upgrade strategy
generating-apis proto, validation, AI annotations, logic stub, server wiring persistence, authorization, business policy
proto-regen regenerating stubs, gateway, OpenAPI, MCP code schema and data-migration strategy

In the same shell used by the prompt, "$CLI" skills install can wire these skills into Claude Code, Codex, Copilot, and Antigravity. Reading .skills/ directly in the project is sufficient for an agent to follow the workflow.

  • /llms.txt: the site index; read it first, then select the needed pages.
  • /llms-full.txt: complete English documentation; use it only when the larger context is justified.

Let an agent call the local service

Section titled “Let an agent call the local service”

The service is an MCP server. /mcp exposes proto methods annotated with gortexa.ai.v1; tools/call goes through auth and validation, but application authorization remains your responsibility.

Terminal window
curl -X POST localhost:8080/mcp \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Export a tool schema with:

Terminal window
"$CLI" export --format=mcp

Details are in the MCP transport.