Skip to content

Debug

Debug (atlas.debug) is the package containing the local debugging server script: server.py.

Server

Atlas local debug server.

This file should not be imported anywhere, except for inside the API's .atlas/debug.py file.

This module implements the local execution environment for Atlas APIs, faithfully simulating an AWS API Gateway + Lambda deployment for both REST and WebSocket interfaces.

It is designed exclusively for local development and debugging, allowing developers to run and test Atlas applications without deploying infrastructure via AWS CDK.

When executed, this server spins up:

An HTTP server
  • Binds to localhost:<port> (default: 8080)
  • Routes incoming HTTP requests to Lambda handlers defined under src/functions
  • Applies the same authorization logic used in production (custom authorizer)
  • Builds Lambda-compatible event payloads
  • Executes handlers in-process
A WebSocket server
  • Binds to localhost:<port + 1> (default: 8081)
  • Simulates API Gateway WebSocket lifecycle: $connect, message routing via channel.action, $disconnect
  • Executes Atlas WebSocket channels and actions like production
  • Persists connections in DynamoDB (ws_connections)
  • Validate public vs. private WebSocket rules
  • Token validation
  • Permission checks
  • Rate limiting
  • Idle TTL expiration
Notes
  • This script is strictly written to work with .atlas/debug.py in VSCode (F5 key).
  • Compared to a real deployment, some logics have been adapted as faithfully as possible, but may differ in several aspects.
  • Infrastructure settings (such as memory, SnapStart usage, rate/burst options and others) will not take effect in this local environment.
  • During debugging, some interactions with AWS may still be necessary (such as using the secret ARN that stores environment variables, reading and writing DynamoDB tables, etc.).
  • Therefore, it's recommended to run this local debug server only after successfully deploying your application at least once.
Example 
# .atlas/debug.py

from atlas.debug import server

# Runs the debug server at the provided port. Use "use_local=True" if you are locally developing atlas-fw (editable) in a neighboring folder.
server.run_server(port=8080, use_local=True)