How to Run a Development Server with Arc-Kit: FastAPI and DevContainer Setup

Run uvicorn main:app --reload --host 0.0.0.0 --port 8000 inside the Arc-Kit devcontainer after generating the DevOps scaffold to launch a hot-reloading FastAPI development server.

Arc-Kit does not ship with a built-in web server, but the tractorjuice/arc-kit repository provides a DevOps command that scaffolds a complete FastAPI application. This guide explains how to run a development server with Arc-Kit using either the automated devcontainer environment or a local Python setup.

Prerequisites: Installing Arc-Kit and Initializing Your Project

Before running a development server, you must install the Arc-Kit CLI and create a project structure. The docs/getting-started.html file (lines 46-66) provides platform-specific installation instructions for Claude Code, Gemini CLI, Codex CLI, OpenCode CLI, and Copilot.

Once installed, run the initialization command:

arckit init my-project --ai codex

The init command, implemented in src/arckit_cli/__init__.py (lines 23-31), copies the necessary templates—including the DevOps scaffold—into your new project directory.

Generating the Development Server Scaffold

Arc-Kit uses a dedicated DevOps command to generate deployment and runtime configurations. In Claude Code, run /arckit.devops "Create API service for demo", or use the equivalent $arckit-devops command in other AI platforms.

This command generates a DEVOPS document based on the template in .arckit/templates/devops-template.md. At line 428 of this template, the scaffold includes a Docker-ready command:

CMD ["python","-m","uvicorn","main:app","--host","0.0.0.0"]

The generated scaffold creates a main.py file containing a FastAPI application instance named app, ready for the Uvicorn server to execute.

Running the Development Server

You can launch the development server either inside the provided devcontainer or on your local machine.

Inside the DevContainer (Recommended)

The Arc-Kit project includes an automated devcontainer configuration generated by the create_devcontainer() function located in scripts/create-sdg-repo.py (lines 295-303). When you open the project in VS Code, it detects the .devcontainer/devcontainer.json file and prompts you to "Reopen in Container."

The devcontainer pre-installs the Python runtime, uvicorn, and other dependencies. Once inside the container, start the server with hot-reload enabled:

uvicorn main:app --reload --host 0.0.0.0 --port 8000

The --host 0.0.0.0 flag ensures the server is reachable from your host machine at http://localhost:8000.

On Your Local Machine (Without Docker)

If you prefer not to use Docker, create a virtual environment and install the required packages:

python -m venv .venv
source .venv/bin/activate
pip install fastapi uvicorn

Then run the same Uvicorn command:

uvicorn main:app --reload

This executes the same CMD instruction defined in the DevOps template, launching your FastAPI application with automatic reloading on code changes.

Verifying Your Server Setup

Once the server is running, verify the installation by navigating to http://localhost:8000/docs in your browser. This endpoint displays the automatically generated Swagger UI documentation for your FastAPI application, confirming that the Arc-Kit scaffold is functioning correctly.

Summary

• Arc-Kit does not include a built-in web server; instead, it provides a DevOps command (/arckit.devops) that scaffolds a FastAPI application.
• The devcontainer configuration is generated by scripts/create-sdg-repo.py (lines 295-303) and provides a Docker-based environment with Python and Uvicorn pre-installed.
• Run uvicorn main:app --reload --host 0.0.0.0 --port 8000 to start the development server with hot-reload enabled.
• The main.py scaffold and Uvicorn command are defined in .arckit/templates/devops-template.md at line 428.

Frequently Asked Questions

Does Arc-Kit include a built-in web server?

No, Arc-Kit does not ship with a pre-built web server. Instead, the repository provides a DevOps command that generates a FastAPI scaffold. You run the development server using standard Python tooling like Uvicorn after generating the scaffold.

What AI platforms are supported by the Arc-Kit CLI?

The Arc-Kit CLI supports multiple AI platforms including Claude Code, Gemini CLI, Codex CLI, OpenCode CLI, and Copilot. The docs/getting-started.html file provides platform-specific installation instructions for each environment.

Can I use a different ASGI server instead of Uvicorn?

While the Arc-Kit DevOps template in .arckit/templates/devops-template.md specifically generates a CMD instruction using Uvicorn, you can modify the generated scaffold to use alternative ASGI servers like Hypercorn or Daphne. However, you must update the Dockerfile or startup commands accordingly after generating the initial scaffold.

Where is the devcontainer configuration generated?

The devcontainer configuration is generated by the create_devcontainer() function located in scripts/create-sdg-repo.py at lines 295-303. This function writes the .devcontainer/devcontainer.json file that VS Code uses to build the Docker-based development environment with Python and Uvicorn pre-installed.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}