Self-Hosted Functions

Edge Functions work out of the box in a self-hosted Supabase setup. The functions service, API gateway routing, and a hello example function are all pre-configured.

Invoke the default function#

The default hello function is located at volumes/functions/hello/index.ts. You can invoke it immediately after starting your stack:

1
curl http://<your-domain>/functions/v1/hello \
2
   --header 'apiKey: <sb_publishable/sb_secret key>'

This returns:

1
{ "message": "Hello from Edge Functions!" }

Create a new function#

Step 1: Add a new function directory and the function code#

1
mkdir -p volumes/functions/my-function &&
2
touch volumes/functions/my-function/index.ts

Add the following code to index.ts:

1
import { withSupabase } from '@supabase/server'
2
3
export default {
4
  fetch: withSupabase({ auth: ['publishable', 'secret'] }, async (req) => {
5
    const { name } = await req.json()
6
    const message = `Hello, ${name}!`
7
8
    return Response.json({ message })
9
  }),
10
}

The auth option controls who can call the function. This example matches the default hello function and requires a publishable or secret API key in the apikey header. 'none' accepts every request, and 'user' requires a valid user JWT. See the Edge Functions auth guide for details.

Step 2: Restart the functions service to pick up the new function#

1
sh run.sh restart functions

Step 3: Invoke your function#

1
curl -X POST http://<your-domain>/functions/v1/my-function \
2
  -H 'apikey: <SUPABASE_PUBLISHABLE_KEY>' \
3
  -H 'Content-Type: application/json' \
4
  -d '{"name": "World"}'

You should be able to see the response from my-function:

1
{ "message": "Hello, World!" }

Custom environment variables#

Using an env file (recommended)#

For multiple variables or secrets, create a separate env file, e.g., .env.functions in your docker/ directory:

1
MY_CUSTOM_VAR=some-value

Add env_file to the functions service in docker-compose.yml (variables in env_file load first, then environment values take precedence):

1
functions:
2
  env_file:
3
    - .env.functions
4
  environment:
5
    # ... existing variables ...

Restart the functions service:

1
sh run.sh recreate functions

Using inline environment variables#

For one or two variables, you can add them directly under environment in docker-compose.yml:

1
functions:
2
  environment:
3
    # Custom variables
4
    MY_CUSTOM_VAR: ${MY_CUSTOM_VAR}
5
    # ... existing variables ...

Then define MY_CUSTOM_VAR in your main .env file, or specify the value directly.

Accessing variables in functions#

All container environment variables are forwarded to the function workers by main/index.ts. Access them with:

1
const customVar = Deno.env.get('MY_CUSTOM_VAR')

Calling Supabase services from functions#

The functions service is pre-configured with the following environment variables:

Here's an example function that queries a table using the admin client provided by @supabase/server:

1
import { withSupabase } from '@supabase/server'
2
3
export default {
4
  fetch: withSupabase({ auth: 'secret' }, async (_req, ctx) => {
5
    // ctx.supabaseAdmin bypasses RLS. This function requires a secret
6
    // API key, so only server-to-server callers can reach it.
7
    const { data, error } = await ctx.supabaseAdmin.from('todos').select('*')
8
9
    return Response.json({ data, error })
10
  }),
11
}

withSupabase reads SUPABASE_URL, the API keys, and SUPABASE_JWKS from the environment variables above. You don't need to wire up createClient yourself.

Internal vs external URLs#

This is a key distinction that affects how you build URLs in your functions:

• SUPABASE_URL contains an internal Docker network hostname. Use it for server-side calls from your functions to other Supabase services (Auth, Storage, database via PostgREST). This is what the Supabase JS client should use inside functions.

• SUPABASE_PUBLIC_URL is the externally-reachable URL of your Supabase instance. Use it if your function needs to build URLs that HTTP clients can reach from the outside.

Managing functions via dashboard#

Self-hosted Studio mounts the same volumes/functions directory as the functions service. You can check what functions are available using Edge Functions > Functions UI.

Deploying functions to a remote server#

To deploy a function to a remote server running self-hosted Supabase, copy the function directory with scp:

1
scp -r ./my-function user@<your-domain>:/path/to/self-hosted/volumes/functions/

Then restart the functions service on the remote host:

1
ssh user@<your-domain> 'cd /path/to/self-hosted && sh run.sh restart functions'

Copying functions from Supabase platform#

If you have existing functions on Supabase platform, you can download them and run them on your self-hosted instance. There are two ways to get the function source code:

• Dashboard - open the function details in Dashboard and click Download.
• Local development & CLI - run supabase functions download <function-name> --remote=<ref> to download the source.

Use scp to copy the function into volumes/functions/<function-name>/ on your self-hosted instance, then restart the functions service.

For more details, see:

• Quick start - Download edge functions
• CLI commands - Download a function

Memory management#

The functions service has two memory limits: a shared container budget and a per-worker limit. Idle-worker cleanup responds to usage of the container budget.

Container memory budget#

FUNCTIONS_MEMORY_LIMIT defaults to 2g, or 2 GiB, in the main docker/.env file. All user workers, the main worker, and page cache share this budget. The monitor excludes inactive file cache when deciding whether to clean up idle workers.

Docker Compose applies this setting through mem_limit. The monitor reads the applied cgroup limit. This is a service resource setting, separate from custom environment variables that function code reads through Deno.env.get().

To change the container budget:

1. In the main docker/.env file, set the limit for your host and functions' memory requirements:

   1
   FUNCTIONS_MEMORY_LIMIT=2g

2. From the docker/ directory, recreate the functions container:

   1
   sh run.sh recreate functions

A restart alone does not apply a changed container limit.

Choose a budget that leaves memory available for the other services on your host. The limit does not reserve host RAM. A 2 GiB budget does not guarantee capacity for 8 workers using 256 MiB each, because workers share the container with other memory consumers.

Per-worker memory limit#

memoryLimitMb in volumes/functions/main/index.ts defaults to 256 MiB per worker. A worker can reach its own limit while the container still has memory available. Increasing this limit allows each worker to consume more of the shared container budget.

To change the per-worker limit:

1. Edit memoryLimitMb in volumes/functions/main/index.ts.

2. From the docker/ directory, restart the functions service:

   1
   sh run.sh restart functions

Idle-worker cleanup#

The monitor uses the container's working set: memory.current minus inactive_file from memory.stat, with a minimum of zero.

The main worker samples the working set every second while it is below 80% of the container limit. At or above 80%, it asks eligible idle workers to retire and requests allocator memory collection. Cleanup skips workers with active requests or pending tasks, including tasks registered with EdgeRuntime.waitUntil().

The monitor waits 5 seconds after each cleanup attempt before sampling again, even when no workers acknowledge retirement. It logs a cleanup warning only when at least one worker acknowledges retirement. An acknowledgment does not mean worker shutdown or memory reclamation has finished. Retiring workers can cause cold starts on later requests.

Monitoring requires a finite cgroup v2 limit and readable memory.current, memory.max, and memory.stat files under /sys/fs/cgroup. An unlimited limit or unavailable files disable monitoring with a warning. After fixing the configuration, run sh run.sh recreate functions from docker/. Other failures trigger retries every 5 seconds, with one warning until recovery.

Per-worker limits still apply. The monitor does not use host memory measurements or guarantee protection from out-of-memory errors. Active tasks, stricter parent cgroup limits, or host memory shortages can still interrupt requests.

Troubleshooting#

404 NOT_FOUND#

The request URL must include the function name after /functions/v1/. For example, /functions/v1/hello. Check that the corresponding directory exists at volumes/functions/hello/.

Function invocation errors#

Inspect the sb-error-code response header and see Edge Functions error codes for details about the error.

Check the functions service logs:

1
docker compose logs functions

For 503 BOOT_ERROR responses without (ref: <uuid>) in the message, check for syntax errors, invalid imports, or missing dependencies that prevent the function from starting.

If the error message includes (ref: <uuid>), the failure occurred in the main worker. Run docker compose logs functions and search for that reference to find the corresponding error.

401 "invalid JWT"#

For more on 401 responses from functions, see Edge Function 401 errors.

• Check that FUNCTIONS_VERIFY_JWT matches your intent (true or false) in .env
• If verification is enabled, pass either a valid JWT in Authorization: Bearer <token> (a user session token or a legacy API key), or an sb_publishable_* or sb_secret_* key in the apikey header. The API gateway translates sb_ keys to an internal JWT, which the functions service then verifies.
• Verifying asymmetric JWTs, including translated sb_ keys, requires SUPABASE_JWKS to be set for the functions service in docker-compose.yml. See New API Keys and Asymmetric Authentication.

Changes to function code not reflected after editing#

Restart the functions service:

1
sh run.sh restart functions

Custom env vars not available in functions#

• Verify the variable is defined in docker-compose.yml (under env_file or environment)
• Recreate the functions container after changing configuration
• Check that the variable name matches exactly (case-sensitive)

Use the following command to recreate the container:

1
sh run.sh recreate functions

Timeout errors#

The default timeouts in volumes/functions/main/index.ts apply to each worker:

To adjust these limits, edit the values in volumes/functions/main/index.ts and restart the functions service.

Requests have a separate idle timeout of 150 seconds. This is set by --user-worker-request-idle-timeout in the functions service command in docker-compose.yml, with the value 150000 in milliseconds. Recreate the functions container after changing this value.

The Envoy gateway has separate limits of 160 seconds of inactivity and a 410-second upstream response timeout.

If you use the optional Kong gateway, read_timeout in volumes/api/kong.yml is set to 160000 milliseconds, allowing 160 seconds of inactivity between reads from the functions service.