Creating Projects

Use arkoren new when you want a new HTTP service with composition, probes, and shutdown already connected. The result is ordinary Go code you own, not a project that needs regeneration. For an existing application, install individual modules instead.

Installing Tools

With Go 1.27 or later, install the CLI:

go install arkoren.dev/cmd/arkoren@latest

Go places it in GOBIN, if set, otherwise under the first GOPATH entry’s bin directory, usually $HOME/go/bin. Put that directory on PATH, then check the available generation options:

arkoren new --help

Help and dry-run work offline. Creation needs no running application or MCP endpoint configuration, but resolves Go dependencies unless you use --skip-tidy. CLI Installation also offers module-tool installation; use go tool arkoren in place of arkoren throughout this page if you choose it.

Previewing Files

Choose a destination and the Go module path your application will keep. From the destination’s parent directory, preview a service named hello:

arkoren new hello --module example.com/hello --dry-run --verbose

The JSON report lists the absolute destination, module, planned files, and conflicts. Without --verbose, it reports counts instead of full inventories. Dry runs do not prompt, write files, or download dependencies. A conflicting plan still returns a nonzero status.

The destination is required; use . explicitly for the current directory. Without --module, the module path is the destination’s basename. Invalid names are rejected, not repaired, so set --module explicitly for shared projects.

Writing Files

Use an unused or empty directory for the ordinary path. After inspecting the preview, write the project:

arkoren new hello --module example.com/hello

Success produces one JSON report containing created: true, the absolute destination, module, and file count. After writing, the CLI runs go mod tidy inside the project with GOWORK=off to download dependencies and populate go.sum. Generation initializes neither Git nor application infrastructure and creates no application tests.

A nonempty destination, even one containing only .git, requires confirmation. The default is no; only a complete y or yes line approves it. Without an interactive terminal, explicitly approve that directory after reviewing its plan:

arkoren new hello --module example.com/hello --yes

This is an alternative invocation, not a second generation step for an already created project. --yes never permits overwriting. Existing files or symlinks at generated paths, unsafe parent paths, case-insensitive filename collisions, and planned file/directory overlaps block generation before writes. Choose another destination or resolve the conflict yourself; there is no automatic merge.

An I/O failure during writing can leave a partial project. Inspect the paths reported by the error before retrying: files already created remain and become conflicts. Do not delete an existing directory merely to clear a generation error.

Resolving Dependencies

Enter the generated project:

cd hello

Dependencies are already resolved after successful creation. Check the code:

go vet ./...

For offline file creation, pass --skip-tidy to arkoren new, then run go mod tidy from the project directory when downloads are available. If automatic dependency setup fails, the CLI exits with an error and preserves the generated files. Retry go mod tidy there instead of rerunning arkoren new.

The starter also declares godotenv for local environment loading, Tint for terminal logs, and go-isatty for terminal detection. They are application dependencies, not dependencies of core. Commit the resolved go.mod and go.sum.

The generated Makefile is optional application tooling. make lists its targets; make check verifies formatting, runs vet, and runs tests without modifying dependencies. make fmt changes formatting. Race tests require a C compiler. Continue to Quickstart to run the service and add your first endpoint.

Starter Defaults

cmd/server/main.go creates the application and calls app.Run(ctx, bootstrap.Compose). Files in internal/bootstrap construct the router, optional diagnostics endpoint, and server. Typed factories return constructed values; the application starts components only after composition succeeds. The generated signal context requests shutdown on Ctrl+C or SIGTERM.

The router serves a welcome page at / and probes at /livez, /readyz, and /startupz. It applies security headers, request telemetry, panic recovery, and same-origin CSRF protection before registering routes. It grants no extra trusted origins or CORS permissions. These defaults are not authentication, host validation, proxy trust, or rate limiting. Keep GET, HEAD, and OPTIONS free of state changes. HSTS requires an explicit HTTPS deployment policy.

The executable loads .env from its working directory without replacing existing environment values; loading errors are ignored. The generated file binds HTTP_ADDR=127.0.0.1:8080 and sets APP_DEBUG=true. Empty or unset HTTP_ADDR falls back to :8080, listening on all interfaces.

Debug mounts unauthenticated diagnostics at /mcp on the main listener. Anyone who can reach it can inspect logs and telemetry attributes. Keep local listeners on loopback and set APP_DEBUG=false in production.

Only the exact value true enables debug. Debug capture retains bounded recent history in memory and loses it on exit; it needs no external telemetry backend. See Capture Setup for customization. If you change the listener address, update ARKOREN_MCP_URL before using CLI diagnostics.

The generated .env is excluded from Git and created with restricted access (POSIX mode 0600, or a protected current-user DACL on Windows). Protect its parent directory too. .env.example disables debug and can be committed. No application secret or signing key is generated; provision credentials only when the feature needs them.

The starter’s logger uses Tint on terminals and JSON when stderr is redirected. NO_COLOR disables terminal colors. Customize Logger() in internal/bootstrap/logging.go, rather than assuming application environment alone selects the starter’s log format.

Agent Files

By default, generation includes AGENTS.md and the bundled documentation skill under .agents/skills/arkoren/, including its installation manifest. Commit them if you use them. Agent discovery varies; configure your agent to read the generated instructions when needed.

If your agent needs a different skills parent, choose it during generation instead of the earlier invocation:

arkoren new hello --module example.com/hello --skills-dir .claude/skills

The CLI appends arkoren and updates the generated pointers. The parent must be a project-relative slash-separated path using letters, digits, dots, underscores, or hyphens, without .. components. File/directory conflicts still block writes.

Alternatively, omit both instructions and the skill with --no-agent-files. Do not combine that flag with a custom --skills-dir. Existing agent-file collisions are not merged or overwritten.

Application files and AGENTS.md remain yours. arkoren skills update manages only the skill directory and rejects modified managed files. There is no application regeneration or upgrade step. Grow the code using Project Layout, and use Deployment when you are ready to build an image or binary.