Quickstart

This quickstart runs jitsudo locally using Docker Compose. You’ll have a fully functional control plane, a mock OIDC provider, and a PostgreSQL database — no cloud credentials required.

Prerequisites: Docker or Podman installed.

1. Clone the repository

   git clone https://github.com/jitsudo-dev/jitsudo
   cd jitsudo

2. Start the local environment

   make docker-up
   export JITSUDO_SERVER=localhost:8443

   This starts:

   • jitsudod — HTTP REST API on localhost:8080, gRPC on localhost:8443
   • PostgreSQL — the database
   • dex — a mock OIDC provider on localhost:5556

3. Install the CLI

   # Homebrew (macOS / Linux)
   brew install jitsudo-dev/tap/jitsudo
   
   # curl installer (macOS / Linux)
   curl -fsSL https://jitsudo.dev/install.sh | sh
   
   # Or build from source
   make build && export PATH="$PWD/bin:$PATH"

4. Log in

   jitsudo login --provider http://localhost:5556/dex

   This opens a device flow. Visit the URL shown in the terminal and log in with a test user:

   • alice@example.com / password
   • bob@example.com / password

5. Submit an elevation request

   jitsudo request \
     --provider mock \
     --role test-role \
     --scope test-scope

   --duration defaults to 1h. --reason is optional (enforceable via policy).

   Note the request ID (e.g., req_01J8KZ...).

6. Approve the request (in another terminal)

   jitsudo login --provider http://localhost:5556/dex  # log in as a different user
   jitsudo approve req_01J8KZ...

7. Use the elevated credentials

   jitsudo exec req_01J8KZ... -- env | grep MOCK

Tip

Run make docker-down to stop the local environment and clean up.

Next steps

• Install jitsudo in a real environment
• Configure a real cloud provider (AWS, Azure, GCP, Kubernetes)
• Set up SSO with your identity provider (Okta, Entra ID, Google Workspace)