> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gravixlayer.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Best Practices

> Design patterns and best practices for building robust agent applications.

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.

<CodeGroup>
  ```python Recommended (Producer Mindset) theme={"theme":{"light":"github-light","dark":"github-dark"}}
  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()
  ```

  ```typescript Recommended (TypeScript) theme={"theme":{"light":"github-light","dark":"github-dark"}}
  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();
  ```

  ```python Not Recommended (Agent-generated Data) theme={"theme":{"light":"github-light","dark":"github-dark"}}
  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()
  ```

  ```typescript Not Recommended (TypeScript) theme={"theme":{"light":"github-light","dark":"github-dark"}}
  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();
  ```
</CodeGroup>

<Tip>
  **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.
</Tip>

## Security: Handling Environment Variables

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

<Warning>
  **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.
</Warning>

### 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.