This guide walks you through your first Takk project, from installation to seeing your application running live. You'll build a simple FastAPI service and deploy it both locally and to the cloud, experiencing the full developer workflow in about 10 minutes.

What You'll Need

Your development machine should have Python 3.9 or later installed. You'll also need Docker running locally, which Takk uses to containerize your application during development. If you don't have Docker yet, grab it from docker.com before continuing.

Access to Takk is currently in public beta. If you haven't signed up yet, head to takk.dev to create an account. Once you're registered, you'll be ready to deploy.

Installing the Takk CLI

Takk works through a command-line tool that handles everything from local development to production deployments. Install it into your project using uv (or pip if you prefer):

uv add takk

Confirm everything worked by checking the version:

takk --version

You should see output showing the installed Takk version. Now you're ready to build your first project.

Creating Your First Project

Let's build a simple API that returns a friendly greeting. Start by creating a new directory for your project:

mkdir my-first-api
cd my-first-api

Every Takk project needs two things: your application code and a project definition that tells Takk how to run it. Create a file called app.py with a basic FastAPI application:

from fastapi import FastAPI

app = FastAPI()

@app.get("/")
def hello():
    return {"message": "Hello from Takk!"}

@app.get("/greet/{name}")
def greet(name: str):
    return {"message": f"Welcome, {name}!"}

This is just standard FastAPI code. Nothing special yet. Now create project.py to tell Takk about your application:

from takk.models import Project, FastAPIApp
from app import app

project = Project(
    name="my-first-api",
    server=FastAPIApp(app),
)

That's it. You've defined a complete Takk project. The server=FastAPIApp(app) line tells Takk to run your FastAPI application as a web server. Takk will handle containers, networking, ports, and everything else.

Running Locally

Before deploying to the cloud, let's see your API running on your laptop. Make sure Docker is running, then execute:

takk up

Takk springs into action. It builds a Docker image containing your application, starts up a local PostgreSQL database (in case you need it later), and launches your FastAPI server. Within a few seconds, you'll see output showing where your application is accessible:

INFO: Container my-first-api is accessible at http://localhost:8000

Open your browser to http://localhost:8000 and you'll see your greeting. Try http://localhost:8000/greet/Alice to see the personalized endpoint in action. Your application is running in the exact same containerized environment it will use in production, giving you confidence that what works locally will work everywhere.

While takk up is running, any changes you make to app.py will automatically reload the server. Try modifying the greeting message and saving. The container restarts instantly with your changes. This hot-reload behavior makes local development fast and responsive, just like running uvicorn --reload directly, but with the added benefit of a production-like environment.

When you're done testing, stop the local environment with:

takk down

This shuts down the containers while preserving any data you might have created. Run takk up again anytime to pick up where you left off.