Best Practices - Gravix Layer

When building autonomous agents, ensuring reliability and deterministic behavior is critical. Follow these best practices to get the most out of Gravix Layer.

The Producer Mindset (File Injection)

When an agent needs to analyze data or process a file, do not instruct the LLM to generate the raw data or fetch it itself if you already have it. Instead, adopt the Producer Mindset: you (the orchestrator) should push the necessary files into the microVM natively using the sandbox.file.write API before asking the agent to act on it.

from gravixlayer import GravixLayer

client = GravixLayer()  # defaults to cloud="aws", region="us-east-1"
sandbox = client.runtime.create()  # defaults to template="base-small"

sandbox.file.write(
    "/workspace/data.csv",
    "Month,Revenue\nJan,45000\nFeb,52000\n",
)

result = sandbox.run_code(
    code="""
import csv
with open('/workspace/data.csv') as f:
    rows = list(csv.DictReader(f))
print(sum(int(row['Revenue']) for row in rows))
""",
)
print(result.text)  # 97000
sandbox.kill()

import { GravixLayer } from 'gravixlayer';

const client = new GravixLayer(); // defaults to cloud="aws", region="us-east-1"
const sandbox = await client.runtime.create(); // defaults to template="base-small"

await sandbox.file.write(
  '/workspace/data.csv',
  'Month,Revenue\nJan,45000\nFeb,52000\n',
);

const result = await sandbox.runCode(`
import csv
with open('/workspace/data.csv') as f:
    rows = list(csv.DictReader(f))
print(sum(int(row['Revenue']) for row in rows))
`);
console.log(result.text); // 97000
await sandbox.kill();

from gravixlayer import GravixLayer

client = GravixLayer()  # defaults to cloud="aws", region="us-east-1"
sandbox = client.runtime.create()  # defaults to template="base-small"

# Asking the LLM to write the file itself wastes tokens and breaks on large datasets.
agent_code = """
with open('/workspace/data.csv', 'w') as f:
    f.write("Month,Revenue\\nJan,45000\\nFeb,52000\\n")
"""
result = sandbox.run_code(code=agent_code)
sandbox.kill()

import { GravixLayer } from 'gravixlayer';

const client = new GravixLayer(); // defaults to cloud="aws", region="us-east-1"
const sandbox = await client.runtime.create(); // defaults to template="base-small"

const agentCode = `
with open('/workspace/data.csv', 'w') as f:
    f.write("Month,Revenue\\nJan,45000\\nFeb,52000\\n")
`;
await sandbox.runCode(agentCode);
await sandbox.kill();

Why this matters: Using the native File APIs prevents token limits from breaking your agent’s code, avoids formatting anomalies when LLMs try to write raw data strings, and drastically reduces the surface area for errors.

Security: Handling Environment Variables

When you pass env_vars during runtime creation, those variables are injected directly into the microVM’s environment.

Agents can see all environment variables. If your agent executes run_cmd(command="env") or Python’s os.environ, it will dump all variables to standard output. Be extremely cautious when injecting production database credentials or LLM API keys if the runtime is executing untrusted or user-generated code.

Recommendations:

Principle of Least Privilege: Only inject keys that the agent absolutely needs.
Ephemeral Keys: If injecting an LLM API key, use short-lived, rate-limited keys where possible.
Proxy Services: Instead of giving the agent raw database credentials, consider hosting an internal MCP server or API proxy that the agent can hit via local network rules, keeping the actual credentials outside the sandbox.